More comments for the advancement API

src/main/java/net/minestom/server/advancements/Advancement.java

@@ -10,7 +10,9 @@ import net.minestom.server.network.player.PlayerConnection;
 import java.util.Date;
 
 /**
- * Represent an advancement situated in an {@link AdvancementTab}
+ * Represents an advancement located in an {@link AdvancementTab}
+ * <p>
+ * All fields are dynamic, changing one will update the advancement in the specific {@link AdvancementTab}
  */
 public class Advancement {
 
@@ -232,18 +234,43 @@ public class Advancement {
         update();
     }
 
+    /**
+     * Set the background
+     * <p>
+     * Only available for {@link AdvancementRoot}
+     *
+     * @param background the new background
+     */
     protected void setBackground(String background) {
         this.background = background;
     }
 
+    /**
+     * Get the identifier of this advancement, used to register the advancement, use it as a parent and to retrieve it later
+     * in the {@link AdvancementTab}
+     *
+     * @return the advancement identifier
+     */
     protected String getIdentifier() {
         return identifier;
     }
 
+    /**
+     * Change the advancement identifier
+     * <p>
+     * WARNING: unsafe, only used by {@link AdvancementTab} to intialize the advancement
+     *
+     * @param identifier the new advancement identifier
+     */
     protected void setIdentifier(String identifier) {
         this.identifier = identifier;
     }
 
+    /**
+     * Get the advancement parent
+     *
+     * @return the advancement parent, null for {@link AdvancementRoot}
+     */
     protected Advancement getParent() {
         return parent;
     }
@@ -342,6 +369,7 @@ public class Advancement {
             final ByteBuf removeBuffer = tab.removeBuffer;
             tab.getViewers().forEach(player -> {
                 final PlayerConnection playerConnection = player.getPlayerConnection();
+                // Receive order is important
                 playerConnection.sendPacket(removeBuffer, true);
                 playerConnection.sendPacket(createBuffer, true);
             });

src/main/java/net/minestom/server/advancements/AdvancementManager.java

@@ -7,14 +7,16 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Used to manages advancement tabs
+ * Used to manage advancement tabs
+ * <p>
+ * Use {@link #createTab(String, AdvancementRoot)} to create a tab with the appropriate {@link AdvancementRoot}
  */
 public class AdvancementManager {
 
     private final Map<String, AdvancementTab> advancementTabMap = new HashMap<>();
 
     /**
-     * Create a new tab with a single advancement
+     * Create a new tab with a single {@link Advancement}
      *
      * @param rootIdentifier the root identifier
      * @param root           the root advancement
@@ -40,7 +42,7 @@ public class AdvancementManager {
     }
 
     /**
-     * Get all the created tab
+     * Get all the created {@link AdvancementTab}
      *
      * @return the collection containing all created {@link AdvancementTab}
      */

src/main/java/net/minestom/server/advancements/AdvancementRoot.java

@@ -4,6 +4,12 @@ import net.minestom.server.chat.ColoredText;
 import net.minestom.server.item.ItemStack;
 import net.minestom.server.item.Material;
 
+/**
+ * Represents an {@link Advancement} which is the root of an {@link AdvancementTab}.
+ * Every tab requires one since advancements needs to be linked to a parent.
+ * <p>
+ * The difference between this and an {@link Advancement} is that the root is responsive for the tab background.
+ */
 public class AdvancementRoot extends Advancement {
 
     public AdvancementRoot(ColoredText title, ColoredText description,

src/main/java/net/minestom/server/advancements/AdvancementTab.java

@@ -13,6 +13,12 @@ import java.util.*;
 
 /**
  * Represents a tab which can be shared between multiple players
+ * <p>
+ * Each tab requires a root advancement and all succeeding advancements need to have a parent in the tab.
+ * You can create a new advancement using {@link #createAdvancement(String, Advancement, Advancement)}
+ * <p>
+ * Be sure to use {@link #addViewer(Player)} and {@link #removeViewer(Player)} to control which players can see this tab.
+ * (all viewers will see the same tab, with the same amount of validated advancements etc... so shared)
  */
 public class AdvancementTab implements Viewable {