From 7371a576d621915c413204b534eaab78314c5ae5 Mon Sep 17 00:00:00 2001 From: Andre_601 <11576465+Andre601@users.noreply.github.com> Date: Tue, 18 Aug 2020 18:37:44 +0200 Subject: [PATCH 1/3] Update Javadoc documentation --- .../me/clip/placeholderapi/events/ExpansionRegisterEvent.java | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java index e1e556f..257b138 100644 --- a/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java +++ b/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java @@ -26,6 +26,10 @@ import org.bukkit.event.Event; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; +/** + * Indicates that a {@link PlaceholderExpansion} has been registered by + * PlaceholderAPI. + */ public final class ExpansionRegisterEvent extends Event implements Cancellable { @NotNull From ab96120911cda9cc371ab3e80ef209759709f1f6 Mon Sep 17 00:00:00 2001 From: Andre601 <11576465+Andre601@users.noreply.github.com> Date: Tue, 18 Aug 2020 23:15:23 +0200 Subject: [PATCH 2/3] More comments... a lot more! --- .../clip/placeholderapi/PlaceholderAPI.java | 28 ++++- .../events/ExpansionRegisterEvent.java | 7 +- .../events/ExpansionUnregisterEvent.java | 11 +- .../expansion/Configurable.java | 2 +- .../expansion/PlaceholderExpansion.java | 117 ++++++++++++++++-- 5 files changed, 147 insertions(+), 18 deletions(-) diff --git a/src/main/java/me/clip/placeholderapi/PlaceholderAPI.java b/src/main/java/me/clip/placeholderapi/PlaceholderAPI.java index ea29cfe..d5d4382 100644 --- a/src/main/java/me/clip/placeholderapi/PlaceholderAPI.java +++ b/src/main/java/me/clip/placeholderapi/PlaceholderAPI.java @@ -139,11 +139,27 @@ public final class PlaceholderAPI { return text.stream().map(line -> setBracketPlaceholders(player, line)) .collect(Collectors.toList()); } - + + /** + * Translates all placeholders into their corresponding values. + *
The pattern of a valid placeholder is {@literal {_}}. + * + * @param player Player to parse the placeholders against + * @param text Text to set the placeholder values in + * @return String containing all translated placeholders + */ public static String setBracketPlaceholders(Player player, String text) { return setBracketPlaceholders((OfflinePlayer) player, text); } - + + /** + * Translates all placeholders into their corresponding values. + *
The pattern of a valid placeholder is {@literal {_}}. + * + * @param player Player to parse the placeholders against + * @param text List of Strings to set the placeholder values in + * @return String containing all translated placeholders + */ public static List setBracketPlaceholders(Player player, List text) { return setPlaceholders((OfflinePlayer) player, text); } @@ -215,7 +231,7 @@ public final class PlaceholderAPI { /** * Get all registered placeholder identifiers * - * @return All registered placeholder identifiers + * @return A Set of type String containing the identifiers of all registered expansions. */ @NotNull public static Set getRegisteredIdentifiers() { @@ -225,6 +241,8 @@ public final class PlaceholderAPI { /** * Get the normal placeholder pattern. + * + * @return Regex Pattern of {@literal [%]([^%]+)[%]} */ public static Pattern getPlaceholderPattern() { return PLACEHOLDER_PATTERN; @@ -232,6 +250,8 @@ public final class PlaceholderAPI { /** * Get the bracket placeholder pattern. + * + * @return Regex Pattern of {@literal [{]([^{}]+)[}]} */ public static Pattern getBracketPlaceholderPattern() { return BRACKET_PLACEHOLDER_PATTERN; @@ -239,6 +259,8 @@ public final class PlaceholderAPI { /** * Get the relational placeholder pattern. + * + * @return Regex Pattern of {@literal [%](rel_)([^%]+)[%]} */ public static Pattern getRelationalPlaceholderPattern() { return RELATIONAL_PLACEHOLDER_PATTERN; diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java index 257b138..0581d46 100644 --- a/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java +++ b/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java @@ -46,7 +46,12 @@ public final class ExpansionRegisterEvent extends Event implements Cancellable { public static HandlerList getHandlerList() { return HANDLERS; } - + + /** + * The {@link PlaceholderExpansion expansion} that was registered. + * + * @return The {@link PlaceholderExpansion} instance. + */ @NotNull public PlaceholderExpansion getExpansion() { return expansion; diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java index b9bebac..d3b45b0 100644 --- a/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java +++ b/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java @@ -25,6 +25,10 @@ import org.bukkit.event.Event; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; +/** + * Indicates that a {@link PlaceholderExpansion} had been unregistered by + * PlaceholderAPI. + */ public final class ExpansionUnregisterEvent extends Event { @NotNull @@ -42,7 +46,12 @@ public final class ExpansionUnregisterEvent extends Event { public static HandlerList getHandlerList() { return HANDLERS; } - + + /** + * The {@link PlaceholderExpansion expansion} that was unregistered. + * + * @return The {@link PlaceholderExpansion} instance. + */ @NotNull public PlaceholderExpansion getExpansion() { return expansion; diff --git a/src/main/java/me/clip/placeholderapi/expansion/Configurable.java b/src/main/java/me/clip/placeholderapi/expansion/Configurable.java index 5660f64..9076d79 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/Configurable.java +++ b/src/main/java/me/clip/placeholderapi/expansion/Configurable.java @@ -24,7 +24,7 @@ import java.util.Map; /** * Any {@link PlaceholderExpansion} class which implements configurable will have any options listed - * in the getDefaults map automatically added to the PlaceholderAPI config.yml file + * in the {@link #getDefaults()} map automatically added to the PlaceholderAPI config.yml file * * @author Ryan McCarthy */ diff --git a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java index 385ce4a..5953160 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java +++ b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java @@ -32,10 +32,17 @@ import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +/** + * Any class extending this will be able to get registered as a PlaceholderExpansion. + *
The registration either happens automatically when the jar file containing a + * class extending this one is located under the {@code PlaceholderAPI/expansions} + * directory or when the {@link #register()} method is called by said class. + */ public abstract class PlaceholderExpansion extends PlaceholderHook { /** - * The placeholder identifier of this expansion + * The placeholder identifier of this expansion. May not contain {@literal %}, + * {@literal {}} or _ * * @return placeholder identifier that is associated with this expansion */ @@ -153,58 +160,139 @@ public abstract class PlaceholderExpansion extends PlaceholderHook { } // === Configuration === - + + /** + * Gets the ConfigurationSection of the expansion located in the config.yml of PlaceholderAPI or + * null when not specified. + *
You may use the {@link Configurable} interface to define default values set + * + * @return ConfigurationSection that this epxpansion has. + */ @Nullable public final ConfigurationSection getConfigSection() { return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier()); } - + + /** + * Gets the ConfigurationSection relative to the {@link #getConfigSection() default one} set + * by the expansion or null when the default ConfigurationSection is null + * + * @param path The path to get the ConfigurationSection from. This is relative to the default section + * @return ConfigurationSection relative to the default section + */ @Nullable public final ConfigurationSection getConfigSection(@NotNull final String path) { final ConfigurationSection section = getConfigSection(); return section == null ? null : section.getConfigurationSection(path); } - + + /** + * Gets the Object relative to the {@link #getConfigSection() default ConfigurationSection} set + * by the expansion or the provided Default Object, when the default ConfigurationSection is null + * + * @param path The path to get the Object from. This is relative to the default section + * @param def The default Object to return when the ConfigurationSection returns null + * @return Object from the provided path or the default one provided + */ @Nullable @Contract("_, !null -> !null") public final Object get(@NotNull final String path, final Object def) { final ConfigurationSection section = getConfigSection(); return section == null ? def : section.get(path, def); } - + + /** + * Gets the int relative to the {@link #getConfigSection() default ConfigurationSection} set + * by the expansion or the provided Default int, when the default ConfigurationSection is null + * + * @param path The path to get the int from. This is relative to the default section + * @param def The default int to return when the ConfigurationSection returns null + * @return int from the provided path or the default one provided + */ public final int getInt(@NotNull final String path, final int def) { final ConfigurationSection section = getConfigSection(); return section == null ? def : section.getInt(path, def); } - + + /** + * Gets the long relative to the {@link #getConfigSection() default ConfigurationSection} set + * by the expansion or the provided Default long, when the default ConfigurationSection is null + * + * @param path The path to get the long from. This is relative to the default section + * @param def The default long to return when the ConfigurationSection returns null + * @return long from the provided path or the default one provided + */ public final long getLong(@NotNull final String path, final long def) { final ConfigurationSection section = getConfigSection(); return section == null ? def : section.getLong(path, def); } - + + /** + * Gets the double relative to the {@link #getConfigSection() default ConfigurationSection} set + * by the expansion or the provided Default double, when the default ConfigurationSection is null + * + * @param path The path to get the double from. This is relative to the default section + * @param def The default double to return when the ConfigurationSection returns null + * @return double from the provided path or the default one provided + */ public final double getDouble(@NotNull final String path, final double def) { final ConfigurationSection section = getConfigSection(); return section == null ? def : section.getDouble(path, def); } - + + /** + * Gets the String relative to the {@link #getConfigSection() default ConfigurationSection} set + * by the expansion or the provided Default String, when the default ConfigurationSection is null + * + * @param path The path to get the String from. This is relative to the default section + * @param def The default String to return when the ConfigurationSection returns null. Can be null + * @return String from the provided path or the default one provided + */ @Nullable @Contract("_, !null -> !null") public final String getString(@NotNull final String path, @Nullable final String def) { final ConfigurationSection section = getConfigSection(); return section == null ? def : section.getString(path, def); } - + + /** + * Gets a String List relative to the {@link #getConfigSection() default ConfigurationSection} set + * by the expansion or an empty List, when the default ConfigurationSection is null + * + * @param path The path to get the String list from. This is relative to the default section + * @return String list from the provided path or an empty list + */ @NotNull public final List getStringList(@NotNull final String path) { final ConfigurationSection section = getConfigSection(); return section == null ? Collections.emptyList() : section.getStringList(path); } - + + /** + * Whether the {@link #getConfigSection() default ConfigurationSection} contains the provided path + * or not. This will return {@code false} when either the default section is null, or doesn't + * contain the provided path + * + * @param path The path to check + * @return true when the default ConfigurationSection is not null and contains the path, false otherwise + */ public final boolean configurationContains(@NotNull final String path) { final ConfigurationSection section = getConfigSection(); return section != null && section.contains(path); } - + + /** + * Whether the provided Object is an instance of this PlaceholderExpansion. + *
This method will perform the following checks in order: + *
    + *
  • Checks if Object equals the class. Returns true when equal and continues otherwise
    • + *
  • Checks if the Object is an instance of a PlaceholderExpansion. Returns false if not
    • + *
  • Checks if the Object's Identifier, Author and version equal the one of this class
    • + *
+ * + * @param o The Object to check + * @return true or false depending on the above mentioned checks + */ @Override public final boolean equals(final Object o) { if (this == o) { @@ -220,7 +308,12 @@ public abstract class PlaceholderExpansion extends PlaceholderHook { getAuthor().equals(expansion.getAuthor()) && getVersion().equals(expansion.getVersion()); } - + + /** + * Returns a String containing the Expansion's name, author and version + * + * @return String containing name, author and version of the expansion + */ @Override public final String toString() { return String.format("PlaceholderExpansion[name: '%s', author: '%s', version: '%s']", getName(), From 9b2ea0587599aef226522cd001bf00c2bd88b92c Mon Sep 17 00:00:00 2001 From: Andre_601 <11576465+Andre601@users.noreply.github.com> Date: Tue, 29 Dec 2020 21:12:22 +0100 Subject: [PATCH 3/3] Improve ExpansionsLoadedEvent's docs --- .../me/clip/placeholderapi/events/ExpansionsLoadedEvent.java | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java index 157b0a0..fa15735 100644 --- a/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java +++ b/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java @@ -26,7 +26,10 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * This event is called when all expansions are loaded (when reloading config, on plugin start and on server load). + * Indicates that all {@link PlaceholderExpansions} have been + * loaded. + *
This event is fired on Server load and when reloading the + * confiuration. */ public class ExpansionsLoadedEvent extends Event {