More docs

18 files changed, 505 insertions, 43 deletions

diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java
index eceaaf23a..162f637b8 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java
@@ -28,11 +28,18 @@ import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 
 /**
- * The area for the + button.
+ * The provider of the area for the + button.
  */
 @FunctionalInterface
 @Environment(EnvType.CLIENT)
 public interface ButtonArea {
+    /**
+     * Returns the default button area provider.
+     * <p>
+     * The button is placed on the right side of the display, aligned to the bottom.
+     *
+     * @return the default button area provider
+     */
     static ButtonArea defaultArea() {
         return bounds -> new Rectangle(bounds.getMaxX() + 2, bounds.getMaxY() - 16, 10, 10);
     }
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java
index 16214baa8..6cd5a368f 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java
@@ -110,23 +110,54 @@ public interface CategoryRegistry extends Reloadable<REIClientPlugin>, Iterable<
         }
     }
     
+    /**
+     * Returns the category configuration for the given category identifier.
+     *
+     * @param category the identifier of the category
+     * @param <T>      the type of the display
+     * @return the category configuration
+     * @throws NullPointerException if no {@link CategoryConfiguration} is found for the given identifier
+     */
     <T extends Display> CategoryConfiguration<T> get(CategoryIdentifier<T> category);
     
+    /**
+     * Returns the category configuration for the given category identifier.
+     *
+     * @param category the identifier of the category
+     * @param <T>      the type of the display
+     * @return the category configuration
+     */
     <T extends Display> Optional<CategoryConfiguration<T>> tryGet(CategoryIdentifier<T> category);
     
+    /**
+     * Configures the category configuration for the given category identifier.
+     * <p>
+     * This method is deferred to when the category is registered. This means that configuration can be
+     * done anytime during the reload phase.
+     *
+     * @param category the identifier of the category
+     * @param action   the action to perform
+     * @param <T>      the type of the display
+     */
     <T extends Display> void configure(CategoryIdentifier<T> category, Consumer<CategoryConfiguration<T>> action);
     
+    /**
+     * Returns the size of the category registry.
+     *
+     * @return the size of the category registry
+     */
     int size();
     
     /**
-     * Registers a category visibility predicate
+     * Registers a category visibility predicate. This is used to determine if a category is visible or not.
      *
      * @param predicate the predicate to be registered
+     * @see CategoryVisibilityPredicate
      */
     void registerVisibilityPredicate(CategoryVisibilityPredicate predicate);
     
     /**
-     * Tests the category against all visibility predicates to determine whether it is visible
+     * Returns whether the category is visible against visibility predicates.
      *
      * @param category the category to test against
      * @return whether the category is visible
@@ -134,7 +165,7 @@ public interface CategoryRegistry extends Reloadable<REIClientPlugin>, Iterable<
     boolean isCategoryVisible(DisplayCategory<?> category);
     
     /**
-     * Tests the category against all visibility predicates to determine whether it is invisible
+     * Returns whether the category is invisible against visibility predicates.
      *
      * @param category the category to test against
      * @return whether the category is invisible
@@ -150,43 +181,82 @@ public interface CategoryRegistry extends Reloadable<REIClientPlugin>, Iterable<
      */
     List<CategoryVisibilityPredicate> getVisibilityPredicates();
     
+    /**
+     * Registers workstations for a category.
+     * <p>
+     * This method is deferred to when the category is registered. This means that registration can be
+     * done anytime during the reload phase.
+     *
+     * @param category the category to register the workstation for
+     * @param stations the workstations to register
+     * @param <D>      the type of the display
+     */
     default <D extends Display> void addWorkstations(CategoryIdentifier<D> category, EntryIngredient... stations) {
         configure(category, config -> config.addWorkstations(stations));
     }
     
+    /**
+     * Registers workstations for a category.
+     * <p>
+     * This method is deferred to when the category is registered. This means that registration can be
+     * done anytime during the reload phase.
+     *
+     * @param category the category to register the workstation for
+     * @param stations the workstations to register
+     * @param <D>      the type of the display
+     */
     default <D extends Display> void addWorkstations(CategoryIdentifier<D> category, EntryStack<?>... stations) {
         configure(category, config -> config.addWorkstations(stations));
     }
     
+    /**
+     * Removes the plus button from a category.
+     *
+     * @param category the category to remove the plus button from
+     * @param <D>      the type of the display
+     * @deprecated No longer supported, the plus button is not available for removal
+     */
     @Deprecated
     @ApiStatus.ScheduledForRemoval
     default <D extends Display> void removePlusButton(CategoryIdentifier<D> category) {
         configure(category, CategoryConfiguration::removePlusButton);
     }
     
+    /**
+     * Sets a plus button area provider for a category.
+     * <p>
+     * This method is deferred to when the category is registered. This means that registration can be
+     * done anytime during the reload phase.
+     *
+     * @param category the category to set the plus button area provider for
+     * @param area     the area provider
+     * @param <D>      the type of the display
+     */
     default <D extends Display> void setPlusButtonArea(CategoryIdentifier<D> category, ButtonArea area) {
         configure(category, config -> config.setPlusButtonArea(area));
     }
     
     interface CategoryConfiguration<T extends Display> extends Identifiable {
         /**
-         * Registers the working stations of a category
+         * Registers workstations for a category.
          *
-         * @param stations the working stations
+         * @param stations the workstations to register
          */
         void addWorkstations(EntryIngredient... stations);
         
         /**
-         * Registers the working stations of a category
+         * Registers workstations for a category.
          *
-         * @param stations the working stations
+         * @param stations the workstations to register
          */
         default void addWorkstations(EntryStack<?>... stations) {
             addWorkstations(CollectionUtils.map(stations, EntryIngredient::of).toArray(new EntryIngredient[0]));
         }
         
         /**
-         * Removes the plus button.
+         * Removes the plus button from a category.
+         *
+         * @deprecated No longer supported, the plus button is not available for removal
          */
         @Deprecated
         @ApiStatus.ScheduledForRemoval
@@ -195,39 +265,64 @@ public interface CategoryRegistry extends Reloadable<REIClientPlugin>, Iterable<
         }
         
         /**
-         * Sets the plus button area
+         * Sets a plus button area provider for a category.
          *
-         * @param area the button area
+         * @param area the area provider
          */
         void setPlusButtonArea(ButtonArea area);
         
         /**
-         * Returns the optional plus button area
+         * Returns the optional plus button area provider
          *
-         * @return the optional plus button area
+         * @return the optional plus button area provider
+         * @implNote This method no longer returns an empty optional
          */
         Optional<ButtonArea> getPlusButtonArea();
         
+        /**
+         * Returns the list of workstations for the category.
+         *
+         * @return the list of workstations for the category
+         */
         List<EntryIngredient> getWorkstations();
         
         /**
+         * Returns the underlying category.
+         *
          * @return the underlying category
          */
         DisplayCategory<T> getCategory();
         
         /**
-         * Gets the display display category identifier
+         * Returns the category identifier
          *
          * @return the identifier of the category
          */
         CategoryIdentifier<?> getCategoryIdentifier();
         
+        /**
+         * Returns an extension for the category.
+         * <p>
+         * An extension may be used to modify how the category set-ups widgets for displays.
+         *
+         * @param provider the provider to register
+         * @see CategoryExtensionProvider
+         */
         @ApiStatus.Experimental
         void registerExtension(CategoryExtensionProvider<T> provider);
         
+        /**
+         * Returns a category view for a display.
+         *
+         * @param display the display
+         * @return the category view
+         */
         @ApiStatus.Experimental
         DisplayCategoryView<T> getView(T display);
         
+        /**
+         * {@inheritDoc}
+         */
         @Override
         default ResourceLocation getIdentifier() {
             return getCategoryIdentifier().getIdentifier();
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java
index 76f9f45ed..666400207 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java
@@ -30,6 +30,14 @@ import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import org.jetbrains.annotations.ApiStatus;
 
+/**
+ * The provider to transform the {@link DisplayCategoryView}s.
+ * <p>
+ * Plugins may use this to alter how a display looks, for example to add a custom widget.
+ *
+ * @param <T> the type of the display
+ * @see me.shedaniel.rei.api.client.registry.category.CategoryRegistry.CategoryConfiguration#registerExtension(CategoryExtensionProvider)
+ */
 @FunctionalInterface
 @ApiStatus.Experimental
 @Environment(EnvType.CLIENT)
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java
index 170d0fdea..af267dc76 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java
@@ -29,13 +29,18 @@ import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import net.minecraft.world.InteractionResult;
 
+/**
+ * Handler for determining the visibility of categories.
+ * This is preferred comparing to removing the categories from the registry.
+ *
+ * @see me.shedaniel.rei.api.client.registry.category.CategoryRegistry#registerVisibilityPredicate(CategoryVisibilityPredicate)
+ */
 @Environment(EnvType.CLIENT)
 public interface CategoryVisibilityPredicate extends Comparable<CategoryVisibilityPredicate> {
     /**
-     * Gets the priority of the handler, the higher the priority, the earlier this is called.
+     * Returns the priority of the handler, the higher the priority, the earlier this is called.
      *
      * @return the priority
-     * @return the priority
      */
     default double getPriority() {
         return 0.0;
@@ -43,15 +48,16 @@ public interface CategoryVisibilityPredicate extends Comparable<CategoryVisibili
     
     /**
      * Handles the visibility of the category.
-     * {@link InteractionResult#PASS} to pass the handling to another handler
-     * {@link InteractionResult#SUCCESS} to always display it
-     * {@link InteractionResult#FAIL} to never display it
      *
      * @param category the category of the display
      * @return the visibility
+     * @see EventResult
      */
     EventResult handleCategory(DisplayCategory<?> category);
     
+    /**
+     * {@inheritDoc}
+     */
     @Override
     default int compareTo(CategoryVisibilityPredicate o) {
         return Double.compare(getPriority(), o.getPriority());
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java
index 435a96569..2759e301e 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java
@@ -39,14 +39,15 @@ import java.util.List;
 
 /**
  * A view that displays a {@link Display}.
+ * <p>
+ * This view can be modified externally with {@link me.shedaniel.rei.api.client.registry.category.extension.CategoryExtensionProvider}.
  *
  * @param <T> the type of display
  */
 @ApiStatus.Experimental
 public interface DisplayCategoryView<T extends Display> {
     /**
-     * Returns the recipe renderer for the display, used
-     * in {@link me.shedaniel.rei.impl.client.gui.screen.CompositeDisplayViewingScreen} for rendering simple recipes.
+     * Returns the recipe renderer for the display, used in composite display viewing screen.
      *
      * @param display the display to render
      * @return the display renderer
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java
index 554994b5b..0af581d55 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java
@@ -70,13 +70,12 @@ public interface DisplayRegistry extends RecipeManagerContext<REIClientPlugin> {
     /**
      * @return the instance of {@link DisplayRegistry}
      */
-    
     static DisplayRegistry getInstance() {
         return PluginManager.getClientInstance().get(DisplayRegistry.class);
     }
     
     /**
-     * Gets the total display count registered
+     * Returns the total display count
      *
      * @return the recipe count
      */
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java
index 7758a88a6..1d0603977 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java
@@ -34,8 +34,8 @@ import java.util.List;
 import java.util.Optional;
 
 /**
- * Interface for generating dynamic displays at runtime.
- * Invoked per display view search, so please keep this performant.
+ * Generator of dynamic displays at runtime.
+ * Invoked per display view search, please keep this performant.
  *
  * @param <T> the type of displays to generate
  * @see DisplayRegistry#registerDisplayGenerator(CategoryIdentifier, DynamicDisplayGenerator)
@@ -43,14 +43,40 @@ import java.util.Optional;
  */
 @Environment(EnvType.CLIENT)
 public interface DynamicDisplayGenerator<T extends Display> {
+    /**
+     * Returns the list of displays generated for querying the recipes of the given stack.
+     * <p>
+     * Displays generated should have the given stack as an output, but that
+     * is not required.
+     *
+     * @param entry the recipes of the stack to query for
+     * @return the list of displays generated
+     * @see ViewSearchBuilder#addRecipesFor(EntryStack)
+     */
     default Optional<List<T>> getRecipeFor(EntryStack<?> entry) {
         return Optional.empty();
     }
     
+    /**
+     * Returns the list of displays generated for querying the usages of the given stack.
+     * <p>
+     * Displays generated should have the given stack as an input, but that
+     * is not required.
+     *
+     * @param entry the usages of the stack to query for
+     * @return the list of displays generated
+     * @see ViewSearchBuilder#addUsagesFor(EntryStack)
+     */
     default Optional<List<T>> getUsageFor(EntryStack<?> entry) {
         return Optional.empty();
     }
     
+    /**
+     * Returns the list of displays generated for a given view search.
+     *
+     * @param builder the builder of the view search
+     * @return the list of displays generated
+     */
     default Optional<List<T>> generate(ViewSearchBuilder builder) {
         return Optional.empty();
     }
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java
index 724d3066e..a02509159 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java
@@ -24,16 +24,23 @@
 package me.shedaniel.rei.api.client.registry.display.visibility;
 
 import me.shedaniel.architectury.event.EventResult;
+import me.shedaniel.rei.api.client.registry.category.visibility.CategoryVisibilityPredicate;
 import me.shedaniel.rei.api.client.registry.display.DisplayCategory;
 import me.shedaniel.rei.api.common.display.Display;
 import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import net.minecraft.world.InteractionResult;
 
+/**
+ * Handler for determining the visibility of displays.
+ * This is preferred comparing to removing the displays from the registry.
+ *
+ * @see me.shedaniel.rei.api.client.registry.display.DisplayRegistry#registerVisibilityPredicate(DisplayVisibilityPredicate)
+ */
 @Environment(EnvType.CLIENT)
 public interface DisplayVisibilityPredicate extends Comparable<DisplayVisibilityPredicate> {
     /**
-     * Gets the priority of the handler, the higher the priority, the earlier this is called.
+     * Returns the priority of the handler, the higher the priority, the earlier this is called.
      *
      * @return the priority
      */
@@ -43,16 +50,17 @@ public interface DisplayVisibilityPredicate extends Comparable<DisplayVisibility
     
     /**
      * Handles the visibility of the display.
-     * {@link InteractionResult#PASS} to pass the handling to another handler
-     * {@link InteractionResult#SUCCESS} to always display it
-     * {@link InteractionResult#FAIL} to never display it
      *
      * @param category the category of the display
      * @param display  the display of the recipe
      * @return the visibility
+     * @see EventResult
      */
     EventResult handleDisplay(DisplayCategory<?> category, Display display);
     
+    /**
+     * {@inheritDoc}
+     */
     @Override
     default int compareTo(DisplayVisibilityPredicate o) {
         return Double.compare(getPriority(), o.getPriority());
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java
index 6ff3af865..b60baec9a 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java
@@ -46,16 +46,17 @@ import java.util.stream.Stream;
 
 /**
  * Registry for registering {@link EntryStack} for display on the overlay entry list.
- *
- * <p>The default REI plugin iterates both {@link Registry#ITEM} and {@link Registry#FLUID}
+ * <p>
+ * The default REI plugin iterates both {@link Registry#ITEM} and {@link Registry#FLUID}
  * to register new entries. Other plugins may override this default behaviour, altering
  * the entry list.
- *
- * <p>REI plugins should only add entries during reload, modifications outside the
- * reload phase may not be reflected immediately.
- *
- * <p>While this registry can be used for registering variants of stacks, there may be
- * native alternatives such as {@link Item#fillItemCategory(CreativeModeTab, NonNullList)}.
+ * <p>
+ * REI plugins should only add entries during reload, modifications outside the
+ * reload phase may not be reflected immediately.<br>
+ * Runtime modifications are also warned about.
+ * <p>
+ * While this registry can be used for registering variants of stacks, there may be
+ * better alternatives such as {@link Item#fillItemCategory(CreativeModeTab, NonNullList)}.
  *
  * @see REIClientPlugin#registerEntries(EntryRegistry)
  */
@@ -80,7 +81,7 @@ public interface EntryRegistry extends Reloadable<REIClientPlugin> {
     
     /**
      * @return the unmodifiable list of filtered entry stacks,
-     * only available after plugins reload.
+     * only available <b>after</b> plugins reload.
      */
     List<EntryStack<?>> getPreFilteredList();
     
@@ -91,7 +92,7 @@ public interface EntryRegistry extends Reloadable<REIClientPlugin> {
     void refilter();
     
     /**
-     * Gets all possible stacks from an item, tries to invoke {@link Item#appendStacks(net.minecraft.item.ItemGroup, net.minecraft.util.collection.DefaultedList)}.
+     * Returns all possible stacks from an item, tries to invoke {@link Item#fillItemCategory(CreativeModeTab, NonNullList)}.
      *
      * @param item the item to find
      * @return the list of possible stacks, will never be empty.
@@ -99,7 +100,7 @@ public interface EntryRegistry extends Reloadable<REIClientPlugin> {
     List<ItemStack> appendStacksForItem(Item item);
     
     /**
-     * Adds an new stack to the entry list.
+     * Adds a new stack to the entry list.
      *
      * @param stack the stack to add
      */
@@ -108,7 +109,7 @@ public interface EntryRegistry extends Reloadable<REIClientPlugin> {
     }
     
     /**
-     * Adds an new stack to the entry list, after a certain stack.
+     * Adds a new stack to the entry list, after a certain stack.
      *
      * @param afterEntry the stack to put after
      * @param stack      the stack to add
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java b/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java
index 61dab5d73..65338fa4e 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java
@@ -24,6 +24,7 @@
 package me.shedaniel.rei.api.client.view;
 
 import me.shedaniel.rei.api.client.ClientHelper;
+import me.shedaniel.rei.api.client.config.ConfigObject;
 import me.shedaniel.rei.api.client.registry.category.CategoryRegistry;
 import me.shedaniel.rei.api.client.registry.display.DisplayCategory;
 import me.shedaniel.rei.api.common.category.CategoryIdentifier;
@@ -38,6 +39,9 @@ import org.jetbrains.annotations.Nullable;
 import java.util.*;
 import java.util.stream.Stream;
 
+/**
+ * Builder for querying displays.
+ */
 public interface ViewSearchBuilder {
     /**
      * Creates a new {@link ViewSearchBuilder} for looking up displays.
@@ -103,6 +107,8 @@ public interface ViewSearchBuilder {
     
     /**
      * Filters the search to only include {@link Display}s that are recipes for the given {@link EntryStack}.
+     * <p>
+     * This will include any {@link Display}s containing {@link Display#getOutputEntries()} that match for the given {@link EntryStack}.
      *
      * @param stack the stack to filter by
      * @param <T>   the type of the stack
@@ -110,10 +116,18 @@ public interface ViewSearchBuilder {
      */
     <T> ViewSearchBuilder addRecipesFor(EntryStack<T> stack);
     
+    /**
+     * Returns the list of {@link EntryStack}s that will be used to filter the search for the recipes of the given {@link EntryStack}.
+     *
+     * @return the list of {@link EntryStack}s
+     * @see ViewSearchBuilder#addRecipesFor(EntryStack)
+     */
     List<EntryStack<?>> getRecipesFor();
     
     /**
      * Filters the search to only include {@link Display}s that are usages for the given {@link EntryStack}.
+     * <p>
+     * This will include any {@link Display}s containing {@link Display#getInputEntries()} that match for the given {@link EntryStack}.
      *
      * @param stack the stack to filter by
      * @param <T>   the type of the stack
@@ -121,10 +135,27 @@ public interface ViewSearchBuilder {
      */
     <T> ViewSearchBuilder addUsagesFor(EntryStack<T> stack);
     
+    /**
+     * Returns the list of {@link EntryStack}s that will be used to filter the search for the usages of the given {@link EntryStack}.
+     *
+     * @return the list of {@link EntryStack}s
+     * @see ViewSearchBuilder#addUsagesFor(EntryStack)
+     */
     List<EntryStack<?>> getUsagesFor();
     
+    /**
+     * Sets the preferred opened {@link DisplayCategory} for the view.
+     *
+     * @param category the preferred opened {@link DisplayCategory}, or {@code null} to use the first category
+     * @return the {@link ViewSearchBuilder} for chaining
+     */
     ViewSearchBuilder setPreferredOpenedCategory(@Nullable CategoryIdentifier<?> category);
     
+    /**
+     * Returns the preferred opened {@link DisplayCategory} for the view, or {@code null} if none is set.
+     *
+     * @return the preferred opened {@link DisplayCategory}
+     */
     @Nullable
     CategoryIdentifier<?> getPreferredOpenedCategory();
     
@@ -141,17 +172,57 @@ public interface ViewSearchBuilder {
     @ApiStatus.Internal
     Map<DisplayCategory<?>, List<DisplaySpec>> buildMapInternal();
     
+    /**
+     * Returns the stream of {@link DisplaySpec}s that match the search.
+     *
+     * @return the stream of {@link DisplaySpec}s
+     */
     @ApiStatus.Experimental
     Stream<DisplaySpec> streamDisplays();
     
+    /**
+     * Returns whether the search is merging equal {@link DisplaySpec}s.
+     *
+     * @return whether the search is merging equal {@link DisplaySpec}s
+     * @see ConfigObject#doMergeDisplayUnderOne() for the config option
+     * @see DisplayCategory#getDisplayMerger() for the merging strategy
+     */
     boolean isMergingDisplays();
     
+    /**
+     * Sets whether the search is merging equal {@link DisplaySpec}s.
+     *
+     * @param mergingDisplays whether the search is merging equal {@link DisplaySpec}s
+     * @return the {@link ViewSearchBuilder} for chaining
+     * @see ConfigObject#doMergeDisplayUnderOne() for the default config option
+     * @see DisplayCategory#getDisplayMerger() for the merging strategy
+     */
     ViewSearchBuilder mergingDisplays(boolean mergingDisplays);
     
+    /**
+     * Returns whether the search is processing visibility handlers.