From d58adb7db839d4bd0f1257e07aa45f9d63c99d7b Mon Sep 17 00:00:00 2001 From: filoghost Date: Sat, 4 Jun 2022 19:11:17 +0200 Subject: [PATCH] Improve API Javadocs --- .../api/HolographicDisplaysAPI.java | 116 ++++++++-- .../holographicdisplays/api/Position.java | 205 ++++++++++++++++++ .../api/hologram/Hologram.java | 30 ++- .../api/hologram/HologramLines.java | 21 +- .../api/hologram/PlaceholderSetting.java | 23 ++ .../api/hologram/VisibilitySettings.java | 38 +++- .../hologram/line/ClickableHologramLine.java | 7 +- .../api/hologram/line/HologramLine.java | 4 +- .../hologram/line/HologramLineClickEvent.java | 14 ++ .../line/HologramLineClickListener.java | 8 +- .../line/HologramLinePickupEvent.java | 14 ++ .../line/HologramLinePickupListener.java | 10 +- .../api/hologram/line/ItemHologramLine.java | 14 +- .../api/hologram/line/TextHologramLine.java | 6 +- .../HolographicDisplaysAPIProvider.java | 3 + .../api/placeholder/GlobalPlaceholder.java | 15 +- .../placeholder/GlobalPlaceholderFactory.java | 14 ++ .../GlobalPlaceholderReplaceFunction.java | 8 +- .../placeholder/IndividualPlaceholder.java | 15 ++ .../IndividualPlaceholderFactory.java | 15 ++ .../IndividualPlaceholderReplaceFunction.java | 8 +- .../api/placeholder/Placeholder.java | 41 ++++ 22 files changed, 558 insertions(+), 71 deletions(-) diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/HolographicDisplaysAPI.java b/api/src/main/java/me/filoghost/holographicdisplays/api/HolographicDisplaysAPI.java index a87933c8..03d97f02 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/HolographicDisplaysAPI.java +++ b/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. + *

+ * 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 - * certain method or class (which may have been added later) is present or not. + * Returns the API version number, which is increased every time the API changes. *

* All public API classes and methods are documented with the Javadoc tag {@code @since}, indicating in which API * version that element was introduced. *

- * It can be used it to require a minimum version, as features may be added (rarely removed) in future versions. The - * first version of the API is 1. + * This number can be used it to require a minimum version, as features may be added (rarely removed) in future + * versions. The first version of the API is 1. *

- * 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 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. + *

+ * 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. + *

+ * 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. + *

+ * 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. + *

+ * 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. + *

+ * 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. + *

+ * 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 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. - *

- * Can be useful to reset placeholders before registering all of them. + * Unregisters all placeholders. * * @since 1 */ diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java b/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java index c313da17..a5411fb9 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/Position.java +++ b/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. Warning: 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(); } diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java index a0654ff8..a1bdfed1 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java +++ b/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. - * To create one see {@link HolographicDisplaysAPI}. + * Group of one or more vertically aligned lines which appear as floating text lines and items. To create one see + * {@link HolographicDisplaysAPI#createHologram(Position)}. + *

+ * 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 - * will throw an exception. Lines will be automatically cleared. - * You should remove all the references of the hologram after deletion. + * Deletes this hologram, clearing the lines. Editing or teleporting the hologram after deleting it throws an + * exception. A deleted hologram should no longer be referenced. * * @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(); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java index f275f102..5067175f 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java +++ b/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 diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java index 975a7488..905f1398 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java +++ b/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 } diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java index 3bb40c8d..2b21a834 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java +++ b/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)}). + *

+ * 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 - * (see {@link #setIndividualVisibility(Player, Visibility)}). + * Sets the global visibility. This value only affects player which do not have an individual visibility (see + * {@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()}). - * The individual visibility value can be removed with {@link #removeIndividualVisibility(Player)}. + * Sets the visibility for a specific player, with precedence over the global visibility + * ({@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 } diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java index d0f4263b..b063d17f 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java +++ b/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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java index 7fe7a371..1e8cdec6 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java +++ b/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 { diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java index 23dcc42d..b8cdfe20 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java +++ b/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}. + *

+ * 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(); } diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java index bbdd4992..523c984d 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java +++ b/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}. + *

+ * 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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java index 7c056715..409e7838 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java +++ b/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}. + *

+ * 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(); } diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java index 6b12c7e6..d8ef706d 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java +++ b/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}. + *

+ * 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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java index d9c5b335..88862f11 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java +++ b/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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java b/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java index a88c792f..87f65c5a 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java +++ b/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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java b/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java index 47958ae7..36a9768d 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java +++ b/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 { diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java index 725e52a2..2f766974 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java +++ b/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. *

- * 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". *

- * Warning: this method should be performance efficient, as it may be invoked often. + * Warning: 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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java index f78c76ae..ffef9c05 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java +++ b/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. + *

+ * 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. + *

+ * 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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java index 0693ee0b..af502dc6 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java +++ b/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 */ diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java index 1ce6f15a..6011a283 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java +++ b/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. + *

+ * 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". + *

+ * Warning: 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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java index 21baebad..060ee9d9 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java +++ b/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. + *

+ * 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. + *

+ * 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); diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java index ea0eb1b7..c9f7d2ad 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java +++ b/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 */ diff --git a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java b/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java index 625d9cec..35151454 100644 --- a/api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java +++ b/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. + *

+ * 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. + *

+ * 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. + *

+ * The valid formats to display the placeholder inside a text line are: + *

+ *

+ * The parts of the placeholder format are: + *

+ *

+ * 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. + *

+ * 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();