Mega Documentation PR

src/main/java/com/cleanroommc/modularui/animation/Animator.java

@@ -63,6 +63,10 @@ public int advance(int elapsedTime) {
         return elapsedTime;
     }
 
+    /**
+     *
+     * @return {@code true} when the animation should be stopped
+     */
     protected boolean onUpdate() {
         return this.onUpdate != null && this.onUpdate.test(getRawValue());
     }
@@ -171,8 +175,9 @@ public Animator curve(IInterpolation curve) {
     }
 
     /**
-     * Sets a function which is executed everytime the progress updates, that is on every frame.
-     * The argument of the function is the interpolated value.
+     * Sets a predicate function which is executed everytime the progress updates, that is on every frame.
+     * The argument of the function is the interpolated value.<br>
+     * The predicate's return value effects {@link Animator#onUpdate()}'s return value.
      *
      * @param onUpdate update function
      * @return this
@@ -183,8 +188,12 @@ public Animator onUpdate(DoublePredicate onUpdate) {
     }
 
     /**
-     * Sets a function which is executed everytime the progress updates, that is on every frame.
-     * The argument of the function is the interpolated value.
+     * Sets a consumer function which is executed everytime the progress updates, that is on every frame.
+     * The argument of the function is the interpolated value.<br>
+     * The consumer will always be wrapped in q {@link DoublePredicate} returning false.
+     *
+     * @see Animator#onUpdate()
+     * @see Animator#onUpdate(DoublePredicate)
      *
      * @param onUpdate update function
      * @return this

src/main/java/com/cleanroommc/modularui/animation/BaseAnimator.java

@@ -94,10 +94,10 @@ public final byte getDirection() {
     }
 
     /**
-     * Sets if the animation should reverse animate once after it finished.
-     * If the animation started in reverse it will animate forward on finish.
+     * Sets if the animation should be reversed after it finished.
+     * If the animation started in reverse, it will animate forwards after finishing.
      *
-     * @param reverseOnFinish if animation should bounce back on finish
+     * @param reverseOnFinish if animation should bounce back after finishing
      * @return this
      */
     public A reverseOnFinish(boolean reverseOnFinish) {
@@ -106,7 +106,7 @@ public A reverseOnFinish(boolean reverseOnFinish) {
     }
 
     /**
-     * Sets how often the animation should repeat. If {@link #reverseOnFinish(boolean)} is set to true, it will repeat the whole cycle.
+     * Sets how often the animation should repeat. If {@link #reverseOnFinish(boolean)} is set to {@code true}, it will repeat the whole cycle.
      * If the number of repeats is negative, it will repeat infinitely.
      *
      * @param repeats how often the animation should repeat.

src/main/java/com/cleanroommc/modularui/animation/MutableObjectAnimator.java

@@ -31,6 +31,12 @@ protected boolean onUpdate() {
         return super.onUpdate();
     }
 
+    /**
+     * Sets an additional consumer function, that gets executed on every progress update (animation frame)
+     * before the {@link Animator#onUpdate()}.
+     * @param consumer the extra consumer
+     * @return this
+     */
     public MutableObjectAnimator<T> intermediateConsumer(Consumer<T> consumer) {
         this.intermediateConsumer = consumer;
         return this;

src/main/java/com/cleanroommc/modularui/animation/ParallelAnimator.java

@@ -16,7 +16,7 @@ public class ParallelAnimator extends BaseAnimator<ParallelAnimator> implements
     public ParallelAnimator(List<IAnimator> animators) {
         this.animators = new ArrayList<>(animators);
         this.animators.forEach(animator -> {
-            if (animator instanceof BaseAnimator baseAnimator) {
+            if (animator instanceof BaseAnimator<?> baseAnimator) {
                 baseAnimator.setParent(this);
             }
         });
@@ -26,7 +26,7 @@ public ParallelAnimator(IAnimator... animators) {
         this.animators = new ArrayList<>();
         Collections.addAll(this.animators, animators);
         this.animators.forEach(animator -> {
-            if (animator instanceof BaseAnimator baseAnimator) {
+            if (animator instanceof BaseAnimator<?> baseAnimator) {
                 baseAnimator.setParent(this);
             }
         });

src/main/java/com/cleanroommc/modularui/api/IPanelHandler.java

@@ -9,13 +9,12 @@
 import org.jetbrains.annotations.ApiStatus;
 
 /**
- * This class can handle opening and closing of a {@link ModularPanel}. It makes sure, that the same panel is not created multiple
- * times and instead reused.
+ * This class handles the opening and closing of a {@link ModularPanel}. It ensures, that the same panel is only created <b>once & reused!</b>
  * <p>Using {@link #openPanel()} is the only way to open multiple panels. </p>
  * <p>Panels can be closed with {@link #closePanel()}, but also with {@link ModularPanel#closeIfOpen()}. With the difference, that the method from this interface also works on server side. </p>
- * Synced panels must be created with {@link PanelSyncManager#panel(String, PanelSyncHandler.IPanelBuilder, boolean)}.
- * If the panel does not contain any synced widgets, a simple panel handler using {@link #simple(ModularPanel, SecondaryPanel.IPanelBuilder, boolean)}
- * is likely what you need.
+ * Synced panels must be created with {@link PanelSyncManager#syncedPanel(String, boolean, PanelSyncHandler.IPanelBuilder)}.
+ * If a panel does not contain any synced widgets, a simple panel handler using {@link #simple(ModularPanel, SecondaryPanel.IPanelBuilder, boolean)}
+ * is likely what you should use.
  */
 @ApiStatus.NonExtendable
 public interface IPanelHandler {
@@ -38,19 +37,20 @@ static IPanelHandler simple(ModularPanel parent, SecondaryPanel.IPanelBuilder pr
     boolean isPanelOpen();
 
     /**
-     * Opens the panel. If there is no cached panel, one will be created.
+     * Opens the panel. If there is no cached panel, it creates one instead.
      * Can be called on both sides if this handler is synced.
      */
     void openPanel();
 
     /**
      * Initiates the closing animation if the panel is open.
+     * This will also close any open sub panel.
      * Can be called on both sides if this handler is synced.
      */
     void closePanel();
 
     /**
-     * Initiates the closing animation of all sub panels.
+     * Initiates the closing animation for all sub panels.
      * Usually for internal use.
      */
     void closeSubPanels();
@@ -78,16 +78,16 @@ default boolean togglePanel() {
 
     /**
      * Deletes the current cached panel. Should not be used frequently.
-     * This only works on panels which don't have {@link ItemSlotSH} sync handlers.
+     * This only works on panels, which don't have synchronized {@link ItemSlotSH} handlers.
      *
-     * @throws UnsupportedOperationException if this handler has ItemSlot sync handlers
+     * @throws UnsupportedOperationException if this handler has synchronized ItemSlot handlers
      */
     void deleteCachedPanel();
 
     /**
      * If this is a sub panel of another panel. A sub panel will be closed when its parent is closed.
      *
-     * @return true if this is a sub panel
+     * @return {@code true} if this is a sub panel
      */
     boolean isSubPanel();
 }

src/main/java/com/cleanroommc/modularui/api/MCHelper.java

@@ -95,6 +95,14 @@ public static FontRenderer getFontRenderer() {
         return null;
     }
 
+    /**
+     * Collects the provided item's tooltip depending on the {@link net.minecraft.client.gui.inventory.GuiContainer} it's displayed in.
+     * If the NEI mod is loaded, then all containers tooltip handlers for the given {@code item} will be executed and their result returned.
+     * Otherwise, each tooltip will be prefixed with a text color. The amount of tooltips depends additionally on the clients advanced tooltip display setting.
+     *
+     * @param item the provided item stack
+     * @return a list of strings representing the processed tooltips for the item stack
+     */
     public static List<String> getItemToolTip(ItemStack item) {
         if (!hasMc()) return Collections.emptyList();
         if (ModularUI.Mods.NEI.isLoaded() && getMc().currentScreen instanceof GuiContainer guiContainer)
@@ -123,6 +131,12 @@ private static List<String> getNEIItemTooltip(ItemStack item, GuiContainer guiCo
         return tooltips;
     }
 
+    /**
+     * Collects the fluid's tooltip, depending on GT5U's loaded state, the clients advanced tooltip display setting and whether shift is pressed.
+     *
+     * @param fluid the provided fluid stack
+     * @return a list of strings representing the processed tooltips for the fluid stack
+     */
     public static List<String> getFluidTooltip(FluidStack fluid) {
         List<String> tooltip = new ArrayList<>();
         tooltip.add(fluid.getLocalizedName());
@@ -141,6 +155,12 @@ public static List<String> getFluidTooltip(FluidStack fluid) {
         return tooltip;
     }
 
+    /**
+     * Collects fluid's additional tooltip, depending on NEI's loaded state and whether shift is pressed.
+     *
+     * @param fluid fluid the provided fluid stack
+     * @return a list of strings representing the processed tooltips for the fluid stack
+     */
     public static List<String> getAdditionalFluidTooltip(FluidStack fluid) {
         List<String> tooltip = new ArrayList<>();
         if (Interactable.hasShiftDown()) {

src/main/java/com/cleanroommc/modularui/api/NEISettings.java

@@ -12,7 +12,9 @@
  * Keeps track of everything related to NEI in a Modular GUI.
  * By default, NEI is disabled in client only GUIs.
  * This class can be safely interacted with even when NEI is not installed.
+ * @see RecipeViewerSettings
  */
+@Deprecated
 @ApiStatus.NonExtendable
 public interface NEISettings {
 

src/main/java/com/cleanroommc/modularui/api/RecipeViewerSettings.java

@@ -35,6 +35,7 @@ public interface RecipeViewerSettings {
 
     /**
      * Only enable recipe viewer in synced GUIs
+     * @see com.cleanroommc.modularui.integration.recipeviewer.RecipeViewerState#DEFAULT RecipeViewerState#DEFAULT
      */
     void defaultState();
 
@@ -46,7 +47,7 @@ public interface RecipeViewerSettings {
      * Checks if recipe viewer is enabled for a given screen
      *
      * @param screen modular screen
-     * @return true if jei is enabled
+     * @return true if recipe viewer is enabled
      */
     boolean isEnabled(ModularScreen screen);
 

src/main/java/com/cleanroommc/modularui/api/UIFactory.java

@@ -33,7 +33,7 @@ public interface UIFactory<D extends GuiData> {
     String getFactoryName();
 
     /**
-     * Creates the main panel for the GUI. Is called on client and server side.
+     * Creates the main panel for the GUI. It's called on client and server side.
      *
      * @param guiData     gui data
      * @param syncManager sync manager
@@ -44,7 +44,7 @@ public interface UIFactory<D extends GuiData> {
     ModularPanel createPanel(D guiData, PanelSyncManager syncManager, UISettings settings);
 
     /**
-     * Creates the screen for the GUI. Is only called on client side.
+     * Creates the screen for the GUI. It's only called on client side.
      *
      * @param guiData   gui data
      * @param mainPanel main panel created in {@link #createPanel(GuiData, PanelSyncManager, UISettings)}
@@ -55,9 +55,9 @@ public interface UIFactory<D extends GuiData> {
     ModularScreen createScreen(D guiData, ModularPanel mainPanel);
 
     /**
-     * Creates the screen wrapper for the GUI. Is only called on client side.
+     * Creates the screen wrapper for the GUI. It's only called on client side.
      *
-     * @param container container for the gui
+     * @param container container for the GUI
      * @param screen    the screen which was created in {@link #createScreen(GuiData, ModularPanel)}
      * @return new screen wrapper
      * @throws IllegalStateException if the wrapping screen is not a {@link net.minecraft.client.gui.inventory.GuiContainer GuiContainer} or if the
@@ -80,20 +80,20 @@ default ModularContainer createContainer() {
     }
 
     /**
-     * A default function to check if the current interacting player can interact with the ui. If not overridden on {@link UISettings},
+     * A default function to check if the current interacting player can interact with the UI. If not overridden on {@link UISettings},
      * then this is called every tick while a UI opened by this factory is open. Once this function returns false, the UI is immediately
      * closed.
      *
      * @param player  current interacting player
      * @param guiData gui data of the current ui
-     * @return if the player can interact with the player.
+     * @return if the player can interact with the UI.
      */
     default boolean canInteractWith(EntityPlayer player, D guiData) {
         return player == guiData.getPlayer();
     }
 
     /**
-     * Writes the gui data to a buffer.
+     * Writes the gui data to the provided buffer.
      *
      * @param guiData gui data
      * @param buffer  buffer
@@ -102,9 +102,9 @@ default boolean canInteractWith(EntityPlayer player, D guiData) {
     void writeGuiData(D guiData, PacketBuffer buffer);
 
     /**
-     * Reads and creates the gui data from the buffer.
+     * Reads and creates the gui data from the provided buffer.
      *
-     * @param player player
+     * @param player current interacting player
      * @param buffer buffer
      * @return new gui data
      */

src/main/java/com/cleanroommc/modularui/api/drawable/IDrawable.java

@@ -61,7 +61,7 @@ default void drawAtZero(GuiContext context, int width, int height, WidgetTheme w
     }
 
     /**
-     * Draws this drawable in a given area. The padding of the area is not applied here.
+     * Draws this drawable in a given area without any padding.
      *
      * @param context     current context to draw with
      * @param area        draw area
@@ -98,7 +98,8 @@ default void drawAtZero(GuiContext context, Area area, WidgetTheme widgetTheme)
     }
 
     /**
-     * Draws this drawable at the current (0|0) with the given area's size and its padding applied (this means its technically not at 0|0).
+     * Draws this drawable always with padding applied at (0|0) shifting the actual drawable content being drawn within
+     * ({@code 0 + padding.left} | {@code 0 + padding.top}) and ({@code area.paddedWith()}|{@code area.paddedHeight()}).<br>
      * This is useful inside widgets since GL is transformed to their position when they are drawing. The padding of the area is not applied
      * here.
      *

src/main/java/com/cleanroommc/modularui/api/drawable/IIcon.java

@@ -13,17 +13,17 @@
 public interface IIcon extends IDrawable {
 
     /**
-     * @return the drawable this icon wraps or null if it doesn't wrap anything
+     * @return the drawable this icon wraps or {@code null} if it doesn't wrap anything
      */
     @Nullable IDrawable getWrappedDrawable();
 
     /**
-     * @return width of this icon or 0 if the width should be dynamic
+     * @return width of this icon or {@code 0} if the width should be dynamic
      */
     int getWidth();
 
     /**
-     * @return height of this icon or 0 of the height should be dynamic
+     * @return height of this icon or {@code 0} of the height should be dynamic
      */
     int getHeight();
 
@@ -42,7 +42,7 @@ default int getDefaultHeight() {
     }
 
     /**
-     * @return the margin of this icon. Only used if width or height is 0
+     * @return the margin of this icon. Only used if width or height is {@code 0}
      */
     Box getMargin();
 
@@ -56,17 +56,17 @@ default IDrawable getRootDrawable() {
     }
 
     /**
-     * This returns a hoverable wrapper of this icon. This is only used in {@link com.cleanroommc.modularui.drawable.text.RichText RichText}.
      * This allows this icon to have its own tooltip.
+     * @return a hoverable wrapper of this icon. This is only used in {@link com.cleanroommc.modularui.drawable.text.RichText RichText}
      */
     default HoverableIcon asHoverable() {
         return new HoverableIcon(this);
     }
 
     /**
-     * This returns an interactable wrapper of this icon. This is only used in
-     * {@link com.cleanroommc.modularui.drawable.text.RichText RichText}. This allows this icon to be able to listen to clicks and other
-     * inputs.
+     * This allows this icon to be able to listen to clicks and other inputs.
+     * @return an interactable wrapper of this icon. This is only used in
+     *         {@link com.cleanroommc.modularui.drawable.text.RichText RichText}.
      */
     default InteractableIcon asInteractable() {
         return new InteractableIcon(this);

src/main/java/com/cleanroommc/modularui/api/drawable/IInterpolation.java

@@ -1,8 +1,9 @@
 package com.cleanroommc.modularui.api.drawable;
 
 /**
- * A function which interpolates between two values.
+ * A functional interface interpolating between two values.
  */
+@FunctionalInterface
 public interface IInterpolation {
 
     /**