[CST-18016] Improved DiscoverResultItemIterator and DiscoverResultIterator java doc

dspace-api/src/main/java/org/dspace/discovery/DiscoverResultItemIterator.java

@@ -18,33 +18,88 @@ import org.dspace.discovery.indexobject.IndexableWorkflowItem;
 import org.dspace.discovery.indexobject.IndexableWorkspaceItem;
 
 /**
- * Extension of {@link DiscoverResultIterator} that iterate over items.
+ * An iterator for discovering and iterating over DSpace items from the search index.
+ * This class extends {@link DiscoverResultIterator} and provides the logic to
+ * handle different types of indexable objects and retrieve the corresponding DSpace items.
+ *
+ * <p>It supports the following indexable object types:</p>
+ * <ul>
+ *   <li>{@link IndexableItem}</li>
+ *   <li>{@link IndexableWorkflowItem}</li>
+ *   <li>{@link IndexableWorkspaceItem}</li>
+ *   <li>{@link IndexablePoolTask}</li>
+ *   <li>{@link IndexableClaimedTask}</li>
+ * </ul>
+ *
+ * <p>Throws an {@link IllegalStateException} if the object type is not recognized.</p>
  *
  * @author Luca Giamminonni (luca.giamminonni at 4science.it)
  */
 public class DiscoverResultItemIterator extends DiscoverResultIterator<Item, UUID> {
 
+    /**
+     * Constructs an iterator for discovering items based on the given context and query.
+     *
+     * @param context       the DSpace context
+     * @param discoverQuery the discovery query
+     */
     public DiscoverResultItemIterator(Context context, DiscoverQuery discoverQuery) {
         super(context, discoverQuery);
     }
 
+    /**
+     * Constructs an iterator with the option to uncache entities.
+     *
+     * @param context the DSpace context
+     * @param discoverQuery the discovery query
+     * @param uncacheEntities whether to uncache entities after iteration
+     */
     public DiscoverResultItemIterator(Context context, DiscoverQuery discoverQuery, boolean uncacheEntities) {
         super(context, discoverQuery, uncacheEntities);
     }
 
+    /**
+     * Constructs an iterator within a specific scope object.
+     *
+     * @param context the DSpace context
+     * @param scopeObject the scope object
+     * @param discoverQuery the discovery query
+     */
     public DiscoverResultItemIterator(Context context, IndexableObject<?, ?> scopeObject, DiscoverQuery discoverQuery) {
         super(context, scopeObject, discoverQuery);
     }
 
+    /**
+     * Constructs an iterator with a limit on the maximum number of results.
+     *
+     * @param context the DSpace context
+     * @param discoverQuery the discovery query
+     * @param maxResults the maximum number of results to return
+     */
     public DiscoverResultItemIterator(Context context, DiscoverQuery discoverQuery, int maxResults) {
         super(context, null, discoverQuery, true, maxResults);
     }
 
+    /**
+     * Constructs an iterator with a scope object and a limit on the maximum number of results.
+     *
+     * @param context the DSpace context
+     * @param scopeObject the scope object
+     * @param discoverQuery the discovery query
+     * @param maxResults the maximum number of results to return
+     */
     public DiscoverResultItemIterator(Context context, IndexableObject<?, ?> scopeObject, DiscoverQuery discoverQuery,
                                       int maxResults) {
         super(context, scopeObject, discoverQuery, true, maxResults);
     }
 
+    /**
+     * Retrieves the next {@link Item} from the iterator. The item is obtained by
+     * determining the type of the next indexable object and extracting the corresponding item.
+     *
+     * @return the next DSpace item
+     * @throws IllegalStateException if the object type is invalid
+     */
     @Override
     public Item next() {
         IndexableObject<?, ?> nextIndexableObject = getNextIndexableObject();
@@ -70,7 +125,7 @@ public class DiscoverResultItemIterator extends DiscoverResultIterator<Item, UUI
             return ((IndexableClaimedTask) nextIndexableObject).getIndexedObject().getWorkflowItem().getItem();
         }
 
-        throw new IllegalStateException("Invalid object type for discover item iterator:" + objectType);
+        throw new IllegalStateException("Invalid object type for discover item iterator: " + objectType);
     }
 
 }

dspace-api/src/main/java/org/dspace/discovery/DiscoverResultIterator.java

@@ -21,7 +21,7 @@ import org.dspace.core.ReloadableEntity;
  *
  * @param <T>  the type of the indexed object
  * @param <PK> the type of the id of the indexed object
- * @author Luca Giamminonni (luca.giamminonni at 4science.it)
+ *
  * @author Luca Giamminonni (luca.giamminonni at 4science.it)
  */
 @SuppressWarnings({"rawtypes", "unchecked"})
@@ -40,18 +40,30 @@ public class DiscoverResultIterator<T extends ReloadableEntity, PK extends Seria
     private DiscoverResult currentDiscoverResult;
     private Iterator<IndexableObject> currentSlotIterator;
 
+    /**
+     * Constructor for global search without scope and unlimited results.
+     */
     public DiscoverResultIterator(Context context, DiscoverQuery discoverQuery) {
         this(context, null, discoverQuery, true, -1);
     }
 
+    /**
+     * Constructor with optional uncacheEntities flag.
+     */
     public DiscoverResultIterator(Context context, DiscoverQuery discoverQuery, boolean uncacheEntities) {
         this(context, null, discoverQuery, uncacheEntities, -1);
     }
 
+    /**
+     * Constructor for scoped search without a limit on the number of results.
+     */
     public DiscoverResultIterator(Context context, IndexableObject<?, ?> scopeObject, DiscoverQuery discoverQuery) {
         this(context, scopeObject, discoverQuery, true, -1);
     }
 
+    /**
+     * Full constructor with all options.
+     */
     public DiscoverResultIterator(Context context, IndexableObject<?, ?> scopeObject, DiscoverQuery discoverQuery,
                                   boolean uncacheEntities, int maxResults) {
 
@@ -66,6 +78,13 @@ public class DiscoverResultIterator<T extends ReloadableEntity, PK extends Seria
         updateCurrentSlotIterator();
     }
 
+    /**
+     * Checks if there are more elements to iterate over.
+     * If the maximum number of results has been reached, it returns false.
+     * Otherwise, it checks the current slot iterator or fetches the next batch of results.
+     *
+     * @return true if there are more elements, false otherwise
+     */
     @Override
     public boolean hasNext() {
         if (maxResults > 0 && iteratorCounter >= maxResults) {
@@ -86,6 +105,9 @@ public class DiscoverResultIterator<T extends ReloadableEntity, PK extends Seria
         return currentSlotIterator.hasNext();
     }
 
+    /**
+     * Returns the next element in the iteration.
+     */
     @Override
     public T next() {
         return (T) getNextIndexableObject().getIndexedObject();
@@ -100,6 +122,10 @@ public class DiscoverResultIterator<T extends ReloadableEntity, PK extends Seria
         return this.currentDiscoverResult.getTotalSearchResults();
     }
 
+    /**
+     * Retrieves the next indexable object.
+     * Throws NoSuchElementException if there are no more elements.
+     */
     protected IndexableObject getNextIndexableObject() {
 
         if (!hasNext()) {