Improve API Javadocs

api/src/main/java/me/filoghost/holographicdisplays/api/HolographicDisplaysAPI.java

@@ -13,7 +13,9 @@ import me.filoghost.holographicdisplays.api.placeholder.GlobalPlaceholderReplace
 import me.filoghost.holographicdisplays.api.placeholder.IndividualPlaceholder;
 import me.filoghost.holographicdisplays.api.placeholder.IndividualPlaceholderFactory;
 import me.filoghost.holographicdisplays.api.placeholder.IndividualPlaceholderReplaceFunction;
+import me.filoghost.holographicdisplays.api.placeholder.Placeholder;
 import org.bukkit.Location;
+import org.bukkit.entity.Player;
 import org.bukkit.plugin.Plugin;
 import org.jetbrains.annotations.NotNull;
 
@@ -21,22 +23,23 @@ import java.util.Collection;
 
 /**
  * Main entry point for accessing the Holographic Displays API.
+ * <p>
+ * Each API instance only manages the holograms and the placeholders of a specific plugin, see {@link #get(Plugin)}.
  *
  * @since 1
  */
 public interface HolographicDisplaysAPI {
 
     /**
-     * Returns the API version number, which is increased every time the API changes. This number is used to check if a
+     * Returns the API version number, which is increased every time the API changes.
-     * certain method or class (which may have been added later) is present or not.
      * <p>
      * All public API classes and methods are documented with the Javadoc tag {@code @since}, indicating in which API
      * version that element was introduced.
      * <p>
-     * It can be used it to require a minimum version, as features may be added (rarely removed) in future versions. The
+     * This number can be used it to require a minimum version, as features may be added (rarely removed) in future
-     * first version of the API is 1.
+     * versions. The first version of the API is 1.
      * <p>
-     * The API version is independent of the normal plugin version.
+     * The API version is unrelated to the standard plugin version.
      *
      * @return the current API version
      * @since 1
@@ -61,57 +64,134 @@ public interface HolographicDisplaysAPI {
     }
 
     /**
-     * Creates a hologram at given location.
+     * Creates a hologram.
      *
-     * @param location the location where it will appear
+     * @param location the initial location of the hologram
      * @return the created hologram
      * @since 1
      */
     @NotNull Hologram createHologram(@NotNull Location location);
 
+    /**
+     * Creates a hologram.
+     *
+     * @param position the initial position of the hologram
+     * @return the created hologram
+     * @since 1
+     */
     @NotNull Hologram createHologram(@NotNull Position position);
 
     /**
-     * Returns all the active holograms. A hologram is no longer active after {@link Hologram#delete()} is invoked.
+     * Returns all the holograms. Deleted holograms are not included.
      *
-     * @return an immutable collection of active holograms
+     * @return an immutable copy of all the holograms
      * @since 1
      */
     @NotNull Collection<Hologram> getHolograms();
 
+    /**
+     * Deletes all the holograms. Equivalent to invoking {@link Hologram#delete()} on each hologram.
+     *
+     * @since 1
+     */
     void deleteHolograms();
 
     /**
+     * Registers a new global placeholder. Any previously registered element (global or individual) with the same
+     * identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
+     * <p>
+     * This is a simplified method to register a placeholder by providing separately its replace function for
+     * {@link GlobalPlaceholder#getReplacement(String)} and a fixed refresh interval for
+     * {@link Placeholder#getRefreshIntervalTicks()}
+     *
+     * @param identifier the case-insensitive identifier of the placeholder
+     * @param refreshIntervalTicks the minimum interval in ticks between invocations of the replace function
+     *         (when the placeholder is in use), see {@link Placeholder#getRefreshIntervalTicks()}
+     * @param replaceFunction the callback function to provide the replacement text to display
      * @since 1
      */
-    void registerGlobalPlaceholder(@NotNull String identifier, int refreshIntervalTicks, @NotNull GlobalPlaceholderReplaceFunction replaceFunction);
+    void registerGlobalPlaceholder(
+            @NotNull String identifier,
+            int refreshIntervalTicks,
+            @NotNull GlobalPlaceholderReplaceFunction replaceFunction);
 
     /**
+     * Registers a new global placeholder. Any previously registered element (global or individual) with the same
+     * identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
+     *
+     * @param identifier the case-insensitive identifier of the placeholder
+     * @param placeholder the placeholder to register
      * @since 1
      */
     void registerGlobalPlaceholder(@NotNull String identifier, @NotNull GlobalPlaceholder placeholder);
 
     /**
+     * Registers a new global placeholder factory. Any previously registered element (global or individual) with the
+     * same identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
+     * <p>
+     * This method is more complex and not usually needed: it is necessary if parsing the argument of the placeholder is
+     * performance intensive, for example a mathematical expression or a JSON string.
+     * <p>
+     * See {@link GlobalPlaceholderFactory} to know more about global placeholder factories.
+     *
+     * @param identifier the case-insensitive identifier of the placeholder factory
+     * @param placeholderFactory the placeholder factory to register
      * @since 1
      */
-    void registerGlobalPlaceholderFactory(@NotNull String identifier, @NotNull GlobalPlaceholderFactory placeholderFactory);
+    void registerGlobalPlaceholderFactory(
+            @NotNull String identifier,
+            @NotNull GlobalPlaceholderFactory placeholderFactory);
 
     /**
+     * Registers a new individual placeholder. Any previously registered element (global or individual) with the
+     * same identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
+     * <p>
+     * This is a simplified method to register a placeholder by providing separately its replace function for
+     * {@link IndividualPlaceholder#getReplacement(Player, String)} and a fixed refresh interval for
+     * {@link Placeholder#getRefreshIntervalTicks()}
+     *
+     * @param identifier the case-insensitive identifier of the placeholder
+     * @param refreshIntervalTicks the minimum interval in ticks between invocations of the replace function for
+     *         each player (when the placeholder is in use), see {@link Placeholder#getRefreshIntervalTicks()}
+     * @param replaceFunction the callback function to provide the replacement text to display
      * @since 1
      */
-    void registerIndividualPlaceholder(@NotNull String identifier, int refreshIntervalTicks, @NotNull IndividualPlaceholderReplaceFunction replaceFunction);
+    void registerIndividualPlaceholder(
+            @NotNull String identifier,
+            int refreshIntervalTicks,
+            @NotNull IndividualPlaceholderReplaceFunction replaceFunction);
 
     /**
+     * Registers a new individual placeholder. Any previously registered element (global or individual) with the same
+     * identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
+     *
+     * @param identifier the case-insensitive identifier of the placeholder
+     * @param placeholder the placeholder to register
      * @since 1
      */
     void registerIndividualPlaceholder(@NotNull String identifier, @NotNull IndividualPlaceholder placeholder);
 
     /**
+     * Registers a new individual placeholder factory. Any previously registered element (global or individual) with the
+     * same identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
+     * <p>
+     * This method is more complex and not usually needed: it is necessary if parsing the argument of the placeholder is
+     * performance intensive, for example a mathematical expression or a JSON string.
+     * <p>
+     * See {@link IndividualPlaceholderFactory} to know more about individual placeholder factories.
+     *
+     * @param identifier the case-insensitive identifier of the placeholder factory
+     * @param placeholderFactory the placeholder factory to register
      * @since 1
      */
-    void registerIndividualPlaceholderFactory(@NotNull String identifier, @NotNull IndividualPlaceholderFactory placeholderFactory);
+    void registerIndividualPlaceholderFactory(
+            @NotNull String identifier,
+            @NotNull IndividualPlaceholderFactory placeholderFactory);
 
     /**
+     * Returns if a placeholder with a given identifier is registered.
+     *
+     * @param identifier the case-insensitive identifier of the placeholder
      * @since 1
      */
     boolean isRegisteredPlaceholder(@NotNull String identifier);
@@ -119,23 +199,21 @@ public interface HolographicDisplaysAPI {
     /**
      * Returns all the registered placeholder identifiers.
      *
-     * @return a collection of placeholder identifiers
+     * @return an immutable copy of the registered placeholder identifiers
      * @since 1
      */
     @NotNull Collection<String> getRegisteredPlaceholders();
 
     /**
-     * Unregisters a placeholder.
+     * Unregisters the placeholder with a given identifier.
      *
-     * @param identifier the identifier of the placeholder to remove
+     * @param identifier the identifier of the placeholder to unregister, case-insensitive
      * @since 1
      */
     void unregisterPlaceholder(@NotNull String identifier);
 
     /**
-     * Resets and removes all the registered placeholders.
+     * Unregisters all placeholders.
-     * <p>
-     * Can be useful to reset placeholders before registering all of them.
      *
      * @since 1
      */

api/src/main/java/me/filoghost/holographicdisplays/api/Position.java

@@ -14,72 +14,277 @@ import org.bukkit.util.Vector;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Represents an immutable 3-dimensional position in a world. Differently from a {@link Location} it holds a reference
+ * to a world's name instead of a {@link World} object directly, making it suitable for unloaded worlds. Another
+ * difference is the lack of yaw and pitch.
+ *
+ * @since 1
+ */
 public interface Position {
 
+    /**
+     * Returns the position with the given world and coordinates.
+     *
+     * @param world the world
+     * @param x the X coordinate
+     * @param y the Y coordinate
+     * @param z the Z coordinate
+     * @return the created position
+     * @since 1
+     */
     static @NotNull Position of(@NotNull World world, double x, double y, double z) {
         return HolographicDisplaysAPIProvider.getImplementation().createPosition(world, x, y, z);
     }
 
+    /**
+     * Returns the position with the given world and coordinates.
+     *
+     * @param worldName the name of the world
+     * @param x the X coordinate
+     * @param y the Y coordinate
+     * @param z the Z coordinate
+     * @return the created position
+     * @since 1
+     */
     static @NotNull Position of(@NotNull String worldName, double x, double y, double z) {
         return HolographicDisplaysAPIProvider.getImplementation().createPosition(worldName, x, y, z);
     }
 
+    /**
+     * Returns the position from a Location.
+     *
+     * @param location the location from which to obtain the position
+     * @return the created position
+     * @since 1
+     */
     static @NotNull Position of(@NotNull Location location) {
         return HolographicDisplaysAPIProvider.getImplementation().getPosition(location);
     }
 
+    /**
+     * Returns the position of an entity.
+     *
+     * @param entity the entity from which to obtain the position
+     * @return the created position
+     * @since 1
+     */
     static @NotNull Position of(@NotNull Entity entity) {
         return HolographicDisplaysAPIProvider.getImplementation().getPosition(entity);
     }
 
+    /**
+     * Returns the position of a block.
+     *
+     * @param block the block from which to obtain the position
+     * @return the created position
+     * @since 1
+     */
     static @NotNull Position of(@NotNull Block block) {
         return HolographicDisplaysAPIProvider.getImplementation().getPosition(block);
     }
 
+    /**
+     * Returns the name of the world of this position.
+     *
+     * @return the world name
+     * @since 1
+     */
     @NotNull String getWorldName();
 
+    /**
+     * Returns the X coordinate of this position.
+     *
+     * @return the X coordinate
+     * @since 1
+     */
     double getX();
 
+    /**
+     * Returns the Y coordinate of this position.
+     *
+     * @return the Y coordinate
+     * @since 1
+     */
     double getY();
 
+    /**
+     * Returns the Z coordinate of this position.
+     *
+     * @return the Z coordinate
+     * @since 1
+     */
     double getZ();
 
+    /**
+     * Returns the loaded world of this position or null if it's not loaded.
+     *
+     * @return the loaded world or null if not loaded
+     * @since 1
+     */
     @Nullable World getWorldIfLoaded();
 
+    /**
+     * Returns if this position is in the same world of another position.
+     *
+     * @param position the position to compare
+     * @return true if the world is the same, false otherwise
+     * @since 1
+     */
     boolean isInSameWorld(@NotNull Position position);
 
+    /**
+     * Returns if this position is in the same world of a Location.
+     *
+     * @param location the location to compare
+     * @return true if the world is the same, false otherwise
+     * @since 1
+     */
     boolean isInSameWorld(@NotNull Location location);
 
+    /**
+     * Returns if this position is in the same world of an entity.
+     *
+     * @param entity the entity to compare
+     * @return true if the world is the same, false otherwise
+     * @since 1
+     */
     boolean isInSameWorld(@NotNull Entity entity);
 
+    /**
+     * Returns if this position is in the given world.
+     *
+     * @param world the world to compare
+     * @return true if the world matches, false otherwise
+     * @since 1
+     */
     boolean isInWorld(@Nullable World world);
 
+    /**
+     * Returns if this position is in the given world name.
+     *
+     * @param worldName the world name to compare
+     * @return true if the world name matches, false otherwise
+     * @since 1
+     */
     boolean isInWorld(@Nullable String worldName);
 
+    /**
+     * Returns the X coordinate of the block in this position.
+     *
+     * @return the block's X coordinate
+     * @since 1
+     */
     int getBlockX();
 
+    /**
+     * Returns the Y coordinate of the block in this position.
+     *
+     * @return the block's Y coordinate
+     * @since 1
+     */
     int getBlockY();
 
+    /**
+     * Returns the Z coordinate of the block in this position.
+     *
+     * @return the block's Z coordinate
+     * @since 1
+     */
     int getBlockZ();
 
+    /**
+     * Returns a new position made by adding the given lengths to each coordinate.
+     *
+     * @param x the length to add to the X coordinate
+     * @param y the length to add to the Y coordinate
+     * @param z the length to add to the Z coordinate
+     * @since 1
+     */
     @NotNull Position add(double x, double y, double z);
 
+    /**
+     * Returns a new position made by subtracting the given lengths from each coordinate.
+     *
+     * @param x the length to subtract from the X coordinate
+     * @param y the length to subtract from the Y coordinate
+     * @param z the length to subtract from the Z coordinate
+     * @since 1
+     */
     @NotNull Position subtract(double x, double y, double z);
 
+    /**
+     * Returns the distance between this position and another position. Avoid repeatedly calling this method as it uses
+     * a costly square-root function, or consider using {@link #distanceSquared(Position)} instead.
+     *
+     * @param position the position from which to measure the distance
+     * @return the distance from the other position
+     * @since 1
+     */
     double distance(@NotNull Position position);
 
+    /**
+     * Returns the distance between this position and a Location. Avoid repeatedly calling this method as it uses
+     * a costly square-root function, or consider using {@link #distanceSquared(Location)} instead.
+     *
+     * @param location the location from which to measure the distance
+     * @return the distance from the Location
+     * @since 1
+     */
     double distance(@NotNull Location location);
 
+    /**
+     * Returns the distance between this position and an entity. Avoid repeatedly calling this method as it uses
+     * a costly square-root function, or consider using {@link #distanceSquared(Entity)} instead.
+     *
+     * @param entity the entity from which to measure the distance
+     * @return the distance from the entity
+     * @since 1
+     */
     double distance(@NotNull Entity entity);
 
+    /**
+     * Returns the squared distance between this position and another position.
+     *
+     * @param position the position from which to measure the distance
+     * @return the squared distance from the other position
+     * @since 1
+     */
     double distanceSquared(@NotNull Position position);
 
+    /**
+     * Returns the squared distance between this position and a Location.
+     *
+     * @param location the location from which to measure the distance
+     * @return the squared distance from the Location
+     * @since 1
+     */
     double distanceSquared(@NotNull Location location);
 
+    /**
+     * Returns the squared distance between this position and an entity.
+     *
+     * @param entity the entity from which to measure the distance
+     * @return the squared distance from the entity
+     * @since 1
+     */
     double distanceSquared(@NotNull Entity entity);
 
+    /**
+     * Returns a new Location derived from this position. <b>Warning</b>: if the world is not loaded, the Location will
+     * contain a null {@link World}, which can lead to unexpected errors.
+     *
+     * @return A new Location based on this position
+     * @since 1
+     */
     @NotNull Location toLocation();
 
+    /**
+     * Returns a new Vector derived from this position.
+     *
+     * @return a new Vector based on this position
+     * @since 1
+     */
     @NotNull Vector toVector();
 
 }

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java

@@ -12,24 +12,27 @@ import org.bukkit.World;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Entity to manage a group of vertically aligned lines, which display floating text and items.
+ * Group of one or more vertically aligned lines which appear as floating text lines and items. To create one see
- * To create one see {@link HolographicDisplaysAPI}.
+ * {@link HolographicDisplaysAPI#createHologram(Position)}.
+ * <p>
+ * The lines are displayed in a top to bottom order starting from the hologram position and going down.
  *
  * @since 1
  */
 public interface Hologram {
 
     /**
-     * Returns the editable list of lines.
+     * Returns the editable lines of this hologram.
      *
+     * @return the editable lines
      * @since 1
      */
     @NotNull HologramLines getLines();
 
     /**
-     * Returns the {@link VisibilitySettings} of this hologram.
+     * Returns the visibility settings.
      *
-     * @return the VisibilitySettings of this hologram
+     * @return the visibility settings
      * @since 1
      */
     @NotNull VisibilitySettings getVisibilitySettings();
@@ -53,7 +56,7 @@ public interface Hologram {
     /**
      * Moves the hologram to the given position.
      *
-     * @param worldName the world name where the hologram should be moved
+     * @param worldName the name of the world where the hologram should be moved
      * @param x the X coordinate
      * @param y the Y coordinate
      * @param z the Z coordinate
@@ -81,28 +84,33 @@ public interface Hologram {
     void setPosition(@NotNull Location location);
 
     /**
+     * Returns the placeholder setting.
+     *
+     * @return the placeholder setting
      * @since 1
      */
     @NotNull PlaceholderSetting getPlaceholderSetting();
 
     /**
+     * Changes the placeholder setting.
+     *
+     * @param placeholderSetting the new placeholder setting
      * @since 1
      */
     void setPlaceholderSetting(@NotNull PlaceholderSetting placeholderSetting);
 
     /**
-     * Deletes this hologram. Editing or teleporting the hologram when deleted
+     * Deletes this hologram, clearing the lines. Editing or teleporting the hologram after deleting it throws an
-     * will throw an exception. Lines will be automatically cleared.
+     * exception. A deleted hologram should no longer be referenced.
-     * You should remove all the references of the hologram after deletion.
      *
      * @since 1
      */
     void delete();
 
     /**
-     * Checks if a hologram was deleted.
+     * Returns if this hologram is deleted.
      *
-     * @return true if this hologram was deleted
+     * @return true if this hologram is deleted
      * @since 1
      */
     boolean isDeleted();

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java

@@ -13,14 +13,15 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * The editable list of lines of a hologram.
+ * The editable lines of a hologram, following a top to bottom order (first line is top one, last line is the bottom
+ * one).
  *
  * @since 1
  */
 public interface HologramLines {
 
     /**
-     * Adds a new text line at the end.
+     * Adds a new text line at the bottom.
      *
      * @param text the content of the line, see {@link TextHologramLine#setText(String)}
      * @return the created line
@@ -29,7 +30,7 @@ public interface HologramLines {
     @NotNull TextHologramLine appendText(@Nullable String text);
 
     /**
-     * Adds a new item line at the end.
+     * Adds a new item line at the bottom.
      *
      * @param itemStack the content of the line, see {@link ItemHologramLine#setItemStack(ItemStack)}
      * @return the created line
@@ -38,9 +39,9 @@ public interface HologramLines {
     @NotNull ItemHologramLine appendItem(@Nullable ItemStack itemStack);
 
     /**
-     * Inserts a new text line before the given index.
+     * Inserts a new text line before the line at the given index, shifting all the lines below.
      *
-     * @param beforeIndex the index before which the line is inserted, 0 to insert as first
+     * @param beforeIndex the index before which the line should be inserted, 0 to insert on top
      * @param text the content of the line, see {@link TextHologramLine#setText(String)}
      * @return the created line
      * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= size())
@@ -49,9 +50,9 @@ public interface HologramLines {
     @NotNull TextHologramLine insertText(int beforeIndex, @Nullable String text);
 
     /**
-     * Inserts a new item line before the given index.
+     * Inserts a new item line before the line at the given index, shifting all the lines below.
      *
-     * @param beforeIndex the index before which the line is inserted, 0 to insert as first
+     * @param beforeIndex the index before which the line should be inserted, 0 to insert on top
      * @param itemStack the content of the line, see {@link ItemHologramLine#setItemStack(ItemStack)}
      * @return the created line
      * @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= size())
@@ -95,15 +96,15 @@ public interface HologramLines {
     void clear();
 
     /**
-     * Returns the amount of lines.
+     * Returns the current amount of lines.
      *
-     * @return the amount of lines
+     * @return the current amount of lines
      * @since 1
      */
     int size();
 
     /**
-     * The total height of the lines, including the gaps between them.
+     * The total height in blocks occupied by the lines, including the gaps between them.
      *
      * @return the total height of the lines
      * @since 1

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java

@@ -5,10 +5,33 @@
  */
 package me.filoghost.holographicdisplays.api.hologram;
 
+/**
+ * The option to enable or disable placeholders inside the text lines of hologram.
+ *
+ * @see Hologram#setPlaceholderSetting(PlaceholderSetting)
+ * @since 1
+ */
 public enum PlaceholderSetting {
 
+    /**
+     * The default setting for placeholders (which is currently equivalent to {@link #DISABLE_ALL}).
+     *
+     * @since 1
+     */
     DEFAULT,
+
+    /**
+     * Enable all placeholders.
+     *
+     * @since 1
+     */
     ENABLE_ALL,
+
+    /**
+     * Disable all placeholders.
+     *
+     * @since 1
+     */
     DISABLE_ALL
 
 }

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java

@@ -9,7 +9,7 @@ import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Settings to manage the visibility of a hologram to players. Allows to set a global visibility and an individual
+ * Settings to manage the visibility of a hologram to players. Allows to set both a global visibility and an individual
  * visibility for specific players.
  *
  * @since 1
@@ -17,7 +17,10 @@ import org.jetbrains.annotations.NotNull;
 public interface VisibilitySettings {
 
     /**
-     * Returns the visibility of the hologram. The initial value is {@link Visibility#VISIBLE}.
+     * Returns the global visibility. This value only affects player which do not have an individual visibility (see
+     * {@link #setIndividualVisibility(Player, Visibility)}).
+     * <p>
+     * The initial value is {@link Visibility#VISIBLE}, which means that all players can see the hologram.
      *
      * @return the visibility
      * @since 1
@@ -25,8 +28,8 @@ public interface VisibilitySettings {
     @NotNull Visibility getGlobalVisibility();
 
     /**
-     * Sets the visibility of the hologram. This value only affects player which do not have an individual visibility
+     * Sets the global visibility. This value only affects player which do not have an individual visibility (see
-     * (see {@link #setIndividualVisibility(Player, Visibility)}).
+     * {@link #setIndividualVisibility(Player, Visibility)}).
      *
      * @param visibility the new visibility
      * @since 1
@@ -34,15 +37,16 @@ public interface VisibilitySettings {
     void setGlobalVisibility(@NotNull Visibility visibility);
 
     /**
-     * Sets the visibility for a specific player, overriding the global value of ({@link #getGlobalVisibility()}).
+     * Sets the visibility for a specific player, with precedence over the global visibility
-     * The individual visibility value can be removed with {@link #removeIndividualVisibility(Player)}.
+     * ({@link #getGlobalVisibility()}). The individual visibility value can be removed with
+     * {@link #removeIndividualVisibility(Player)}.
      *
      * @since 1
      */
     void setIndividualVisibility(@NotNull Player player, @NotNull Visibility visibility);
 
     /**
-     * Removes the individual visibility for a player. The visibility for the player would then be determined by the
+     * Removes the individual visibility for a player. The visibility for the player will then be determined by the
      * global visibility ({@link #getGlobalVisibility()}).
      *
      * @since 1
@@ -50,7 +54,8 @@ public interface VisibilitySettings {
     void removeIndividualVisibility(@NotNull Player player);
 
     /**
-     * Removes the individual visibility of all players which have one.
+     * Removes the individual visibility for all players. The visibility for all players will then be determined by the
+     * global visibility ({@link #getGlobalVisibility()}).
      *
      * @since 1
      */
@@ -58,7 +63,7 @@ public interface VisibilitySettings {
 
     /**
      * Checks if a hologram is visible to a player, taking into account both the global visibility and the individual
-     * visibility of the player (if set).
+     * visibility for the player (if set).
      *
      * @param player the player
      * @return if the player can see the hologram
@@ -68,11 +73,24 @@ public interface VisibilitySettings {
 
 
     /**
-     * The available statuses for the visibility of a hologram.
+     * The visibility status of a hologram, which can be set both globally and for individual players.
+     *
+     * @since 1
      */
     enum Visibility {
 
+        /**
+         * The hologram is visible.
+         *
+         * @since 1
+         */
         VISIBLE,
+
+        /**
+         * The hologram is not visible.
+         *
+         * @since 1
+         */
         HIDDEN
 
     }

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java

@@ -8,7 +8,8 @@ package me.filoghost.holographicdisplays.api.hologram.line;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * A hologram line that can be clicked (left or right click).
+ * A hologram line that can be left-clicked or right-click. Currently, both {@link TextHologramLine} and
+ * {@link ItemHologramLine} are clickable.
  *
  * @since 1
  */
@@ -17,7 +18,7 @@ public interface ClickableHologramLine extends HologramLine {
     /**
      * Returns the current click listener.
      *
-     * @return the current click listener, null if not present
+     * @return the current click listener, null if absent
      * @since 1
      */
     @Nullable HologramLineClickListener getClickListener();
@@ -25,7 +26,7 @@ public interface ClickableHologramLine extends HologramLine {
     /**
      * Sets the click listener.
      *
-     * @param clickListener the new click listener, null to unset
+     * @param clickListener the new click listener, null to remove it
      * @since 1
      */
     void setClickListener(@Nullable HologramLineClickListener clickListener);

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java

@@ -6,8 +6,10 @@
 package me.filoghost.holographicdisplays.api.hologram.line;
 
 /**
- * Interface to represent a line in a Hologram.
+ * A line of a hologram.
  *
+ * @see TextHologramLine
+ * @see ItemHologramLine
  * @since 1
  */
 public interface HologramLine {

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java

@@ -7,8 +7,22 @@ package me.filoghost.holographicdisplays.api.hologram.line;
 
 import org.bukkit.entity.Player;
 
+/**
+ * The event of a player clicking on a {@link ClickableHologramLine}.
+ * <p>
+ * This is not a Bukkit event, the listener must be set with
+ * {@link ClickableHologramLine#setClickListener(HologramLineClickListener)}.
+ *
+ * @since 1
+ */
 public interface HologramLineClickEvent {
 
+    /**
+     * Returns the player who clicked on the line.
+     *
+     * @return the player who clicked
+     * @since 1
+     */
     Player getPlayer();
 
 }

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java

@@ -8,7 +8,10 @@ package me.filoghost.holographicdisplays.api.hologram.line;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Interface to handle clickable hologram lines.
+ * The listener class for {@link HologramLineClickEvent}.
+ * <p>
+ * This is not a Bukkit listener, it must be set with
+ * {@link ClickableHologramLine#setClickListener(HologramLineClickListener)}.
  *
  * @since 1
  */
@@ -16,6 +19,9 @@ import org.jetbrains.annotations.NotNull;
 public interface HologramLineClickListener {
 
     /**
+     * Invoked when a player clicks on the clickable line.
+     *
+     * @param clickEvent the event data
      * @since 1
      */
     void onClick(@NotNull HologramLineClickEvent clickEvent);

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java

@@ -7,8 +7,22 @@ package me.filoghost.holographicdisplays.api.hologram.line;
 
 import org.bukkit.entity.Player;
 
+/**
+ * The event of a player being in pickup range of an {@link ItemHologramLine}.
+ * <p>
+ * This is not a Bukkit event, the listener must be set with
+ * {@link ItemHologramLine#setPickupListener(HologramLinePickupListener)}.
+ *
+ * @since 1
+ */
 public interface HologramLinePickupEvent {
 
+    /**
+     * Returns the player being in pickup range of the item line.
+     *
+     * @return the player in pickup range of the item line
+     * @since 1
+     */
     Player getPlayer();
 
 }

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java

@@ -8,7 +8,10 @@ package me.filoghost.holographicdisplays.api.hologram.line;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Interface to handle hologram lines being picked up by players.
+ * The listener class for {@link HologramLinePickupEvent}.
+ * <p>
+ * This is not a Bukkit listener, it must be set with
+ * {@link ItemHologramLine#setPickupListener(HologramLinePickupListener)}.
  *
  * @since 1
  */
@@ -16,6 +19,11 @@ import org.jetbrains.annotations.NotNull;
 public interface HologramLinePickupListener {
 
     /**
+     * Invoked when a player is being in pickup range of the item line. Note that this method is invoked repeatedly
+     * every tick until the player moves out of range, the listener is removed, the item line is no longer visible to
+     * the player, or the item line is removed.
+     *
+     * @param pickupEvent the event data
      * @since 1
      */
     void onPickup(@NotNull HologramLinePickupEvent pickupEvent);

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java

@@ -9,22 +9,24 @@ import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * A hologram line displaying an item.
+ *
  * @since 1
  */
 public interface ItemHologramLine extends ClickableHologramLine {
 
     /**
-     * Returns the ItemStack of this ItemLine.
+     * Returns the currently displayed item.
      *
-     * @return the ItemStack if this ItemLine.
+     * @return the current item
      * @since 1
      */
     @Nullable ItemStack getItemStack();
 
     /**
-     * Sets the ItemStack for this ItemLine.
+     * Sets the displayed item.
      *
-     * @param itemStack the new item, should not be null.
+     * @param itemStack the new item, null to display air
      * @since 1
      */
     void setItemStack(@Nullable ItemStack itemStack);
@@ -32,7 +34,7 @@ public interface ItemHologramLine extends ClickableHologramLine {
     /**
      * Returns the current pickup listener.
      *
-     * @return the current pickup listener, null if not present
+     * @return the current pickup listener, null if absent
      * @since 1
      */
     @Nullable HologramLinePickupListener getPickupListener();
@@ -40,7 +42,7 @@ public interface ItemHologramLine extends ClickableHologramLine {
     /**
      * Sets the pickup listener.
      *
-     * @param pickupListener the new pickup listener, null to unset
+     * @param pickupListener the new pickup listener, null to remove it
      * @since 1
      */
     void setPickupListener(@Nullable HologramLinePickupListener pickupListener);

api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java

@@ -8,6 +8,8 @@ package me.filoghost.holographicdisplays.api.hologram.line;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * A hologram line displaying text.
+ *
  * @since 1
  */
 public interface TextHologramLine extends ClickableHologramLine {
@@ -15,7 +17,7 @@ public interface TextHologramLine extends ClickableHologramLine {
     /**
      * Returns the currently displayed text.
      *
-     * @return the currently displayed text.
+     * @return the current text
      * @since 1
      */
     @Nullable String getText();
@@ -23,7 +25,7 @@ public interface TextHologramLine extends ClickableHologramLine {
     /**
      * Sets the displayed text.
      *
-     * @param text the new displayed text.
+     * @param text the new text
      * @since 1
      */
     void setText(@Nullable String text);

api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java

@@ -14,6 +14,9 @@ import org.bukkit.entity.Entity;
 import org.bukkit.plugin.Plugin;
 import org.jetbrains.annotations.ApiStatus.Internal;
 
+/**
+ * This class is used internally and can change without notice, do not use it.
+ */
 @Internal
 public abstract class HolographicDisplaysAPIProvider {
 

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java

@@ -8,18 +8,25 @@ package me.filoghost.holographicdisplays.api.placeholder;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * A global placeholder that displays the same text to all players. See {@link Placeholder} for general information
+ * about placeholders.
+ *
  * @since 1
  */
 public interface GlobalPlaceholder extends Placeholder {
 
     /**
-     * Callback for providing a placeholder replacement, given the argument of the placeholder (if present).
+     * Callback for providing a placeholder replacement for a given optional argument. The same replacement is shown to
+     * all players.
      * <p>
-     * For example, the argument of {test} is null, the argument of {test: hello world} is the string "hello world".
+     * The argument is provided through the placeholder text: for example, the argument of {test} is null, the argument
+     * of {test: hello world} is the string "hello world".
      * <p>
-     * <b>Warning</b>: this method should be performance efficient, as it may be invoked often.
+     * <b>Warning</b>: the implementation should be performance efficient, as it may be invoked often depending on the
+     * refresh interval of the placeholder.
      *
-     * @return the placeholder replacement
+     * @param argument the optional placeholder argument, null if not specified
+     * @return the optional placeholder replacement, null to leave the placeholder unreplaced
      * @since 1
      */
     @Nullable String getReplacement(@Nullable String argument);

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java

@@ -8,11 +8,25 @@ package me.filoghost.holographicdisplays.api.placeholder;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * Advanced class to create separate {@link GlobalPlaceholder} instances depending on the placeholder argument, instead
+ * of providing a single one when registering the placeholder.
+ * <p>
+ * This is mostly used for performance reasons, to parse the argument only when necessary, instead of doing it every
+ * time the method {@link GlobalPlaceholder#getReplacement(String)} is invoked. For example, the argument might consist
+ * of multiple comma-separated values, be a JSON string, or require a regular expression to parse it.
+ * <p>
+ * Another less common use case is to keep a separate internal state for each different argument.
+ *
  * @since 1
  */
 public interface GlobalPlaceholderFactory {
 
     /**
+     * Returns the placeholder instance to provide the replacement for the given argument. This method might be invoked
+     * again for the same argument if the placeholder is temporarily unused (not displayed to any player).
+     *
+     * @param argument the argument for which the placeholder instance will provide the replacement
+     * @return the placeholder instance
      * @since 1
      */
     @Nullable GlobalPlaceholder getPlaceholder(@Nullable String argument);

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java

@@ -5,10 +5,14 @@
  */
 package me.filoghost.holographicdisplays.api.placeholder;
 
+import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Simple callback to provide a placeholder replacement.
+ * Simplified version of {@link GlobalPlaceholder} where the refresh interval in ticks is passed through the
+ * registration method
+ * {@link HolographicDisplaysAPI#registerGlobalPlaceholder(String, int, GlobalPlaceholderReplaceFunction)} as a
+ * constant.
  *
  * @since 1
  */
@@ -16,7 +20,7 @@ import org.jetbrains.annotations.Nullable;
 public interface GlobalPlaceholderReplaceFunction {
 
     /**
-     * @see GlobalPlaceholder#getReplacement(String)
+     * Same as {@link GlobalPlaceholder#getReplacement(String)}.
      *
      * @since 1
      */

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java

@@ -10,11 +10,26 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * An individual placeholder that can display a different text to each player. See {@link Placeholder} for general
+ * information about placeholders.
+ *
  * @since 1
  */
 public interface IndividualPlaceholder extends Placeholder {
 
     /**
+     * Callback for providing a placeholder replacement for a given player and an optional argument. A different
+     * replacement can be shown to each player.
+     * <p>
+     * The argument is provided through the placeholder text: for example, the argument of {test} is null, the argument
+     * of {test: hello world} is the string "hello world".
+     * <p>
+     * <b>Warning</b>: the implementation should be performance efficient, as it may be invoked often depending on the
+     * refresh interval of the placeholder and the number of players viewing the hologram.
+     *
+     * @param player the player that will see the provided replacement
+     * @param argument the optional placeholder argument, null if not specified
+     * @return the optional placeholder replacement, null to leave the placeholder unreplaced
      * @since 1
      */
     @Nullable String getReplacement(@NotNull Player player, @Nullable String argument);

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java

@@ -5,14 +5,29 @@
  */
 package me.filoghost.holographicdisplays.api.placeholder;
 
+import org.bukkit.entity.Player;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * Advanced class to create separate {@link IndividualPlaceholder} instances depending on the placeholder argument,
+ * instead of providing a single one when registering the placeholder.
+ * <p>
+ * This is mostly used for performance reasons, to parse the argument only when necessary, instead of doing it every
+ * time the method {@link IndividualPlaceholder#getReplacement(Player, String)} is invoked. For example, the argument
+ * might consist of multiple comma-separated values, be a JSON string, or require a regular expression to parse it.
+ * <p>
+ * Another less common use case is to keep a separate internal state for each different argument.
+ *
  * @since 1
  */
 public interface IndividualPlaceholderFactory {
 
     /**
+     * Returns the placeholder instance to provide the replacement for the given argument. This method might be invoked
+     * again for the same argument if the placeholder is temporarily unused (not displayed to any player).
+     *
+     * @param argument the argument for which the placeholder instance will provide the replacement
+     * @return the placeholder instance
      * @since 1
      */
     @Nullable IndividualPlaceholder getPlaceholder(@Nullable String argument);

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java

@@ -5,18 +5,24 @@
  */
 package me.filoghost.holographicdisplays.api.placeholder;
 
+import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * Simplified version of {@link IndividualPlaceholder} where the refresh interval in ticks is passed through the
+ * registration method
+ * {@link HolographicDisplaysAPI#registerIndividualPlaceholder(String, int, IndividualPlaceholderReplaceFunction)} as a
+ * constant.
+ *
  * @since 1
  */
 @FunctionalInterface
 public interface IndividualPlaceholderReplaceFunction {
 
     /**
-     * @see IndividualPlaceholder#getReplacement(Player, String)
+     * Same as {@link IndividualPlaceholder#getReplacement(Player, String)}.
      *
      * @since 1
      */

api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java

@@ -5,9 +5,50 @@
  */
 package me.filoghost.holographicdisplays.api.placeholder;
 
+import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
+import me.filoghost.holographicdisplays.api.hologram.Hologram;
+import me.filoghost.holographicdisplays.api.hologram.PlaceholderSetting;
+
+/**
+ * A placeholder is a dynamic text value that can be displayed in a text hologram line.
+ * <p>
+ * Placeholders can be global (show the same text to all players) or individual (show a different text to each player).
+ * Global placeholders are preferable when possible, as individual placeholders have a higher performance impact.
+ * <p>
+ * To add a placeholder a class must implement either {@link GlobalPlaceholder} or {@link IndividualPlaceholder}, then
+ * it must be registered with {@link HolographicDisplaysAPI#registerGlobalPlaceholder(String, GlobalPlaceholder)} or
+ * {@link HolographicDisplaysAPI#registerIndividualPlaceholder(String, IndividualPlaceholder)} by providing an
+ * identifier string.
+ * <p>
+ * The valid formats to display the placeholder inside a text line are:
+ * <ul>
+ * <li>{identifier}
+ * <li>{identifier: argument}
+ * <li>{plugin/identifier}
+ * <li>{plugin/identifier: argument}
+ * </ul>
+ * <p>
+ * The parts of the placeholder format are:
+ * <ul>
+ * <li>Identifier (required): the identifier used to register the placeholder.
+ * <li>Argument (optional): the argument passed to the replacement callback.
+ * <li>Plugin (optional): the name of the plugin to disambiguate if more plugins register the same identifier.
+ * </ul>
+ * <p>
+ * Placeholders are disabled by default and need to be enabled with
+ * {@link Hologram#setPlaceholderSetting(PlaceholderSetting)}.
+ *
+ * @since 1
+ */
 public interface Placeholder {
 
     /**
+     * Returns the minimum interval in ticks between invocations of the replacement callback. For individual
+     * placeholders the interval is counted separately for each player.
+     * <p>
+     * Note that more ticks can pass between invocations if no player is near, do not use the replacement callback as a
+     * timer.
+     *
      * @since 1
      */
     int getRefreshIntervalTicks();