Merge pull request #443 from PlaceholderAPI/feature/update-documentation

Update Javadoc documentation

src/main/java/me/clip/placeholderapi/PlaceholderAPI.java

@@ -140,11 +140,27 @@ public final class PlaceholderAPI {
     return text.stream().map(line -> setBracketPlaceholders(player, line))
         .collect(Collectors.toList());
   }
-
+  
+  /**
+   * Translates all placeholders into their corresponding values.
+   * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
+   *
+   * @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.
+   * <br>The pattern of a valid placeholder is {@literal {<identifier>_<params>}}.
+   *
+   * @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<String> setBracketPlaceholders(Player player, List<String> text) {
     return setPlaceholders((OfflinePlayer) player, text);
   }
@@ -216,7 +232,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<String> getRegisteredIdentifiers() {
@@ -226,8 +242,8 @@ public final class PlaceholderAPI {
 
   /**
    * Get the normal placeholder pattern.
-   *
-   * @return The default Placeholder Pattern
+   * 
+   * @return Regex Pattern of {@literal [%]([^%]+)[%]}
    */
   public static Pattern getPlaceholderPattern() {
     return PLACEHOLDER_PATTERN;
@@ -235,8 +251,8 @@ public final class PlaceholderAPI {
 
   /**
    * Get the bracket placeholder pattern.
-   *
-   * @return the Bracket Placeholder Pattern
+   * 
+   * @return Regex Pattern of {@literal [{]([^{}]+)[}]}
    */
   public static Pattern getBracketPlaceholderPattern() {
     return BRACKET_PLACEHOLDER_PATTERN;
@@ -244,8 +260,8 @@ public final class PlaceholderAPI {
 
   /**
    * Get the relational placeholder pattern.
-   *
-   * @return The Relational Placeholder Pattern
+   * 
+   * @return Regex Pattern of {@literal [%](rel_)([^%]+)[%]}
    */
   public static Pattern getRelationalPlaceholderPattern() {
     return RELATIONAL_PLACEHOLDER_PATTERN;

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
@@ -42,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;

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;

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 <b>all</b> {@link PlaceholderExpansions} have been
+ * loaded.
+ * <br/>This event is fired on Server load and when reloading the
+ * confiuration.
  */
 public class ExpansionsLoadedEvent extends Event {
 

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
  */

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.
+ * <br>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,64 +160,153 @@ 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.
+   * <br>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<String> getStringList(@NotNull final String path) {
     final ConfigurationSection section = getConfigSection();
     return section == null ? Collections.emptyList() : section.getStringList(path);
   }
   
+  /**
+   * Gets the boolean relative to the {@link #getConfigSection() default ConfigurationSection} set
+   * by the expansion or the default boolean, when the default ConfigurationSection is null
+   *
+   * @param path The path to get the boolean from. This is relative to the default section
+   * @param def The default boolean to return when the ConfigurationSection is null
+   * @return boolean from the provided path or the default one provided
+   */
   @NotNull
   public final boolean getBoolean(@NotNull final String path, final boolean def) {
     final ConfigurationSection section = getConfigSection();
     return section == null ? def : section.getBoolean(path, def);
   }
 
+  /**
+   * 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.
+   * <br>This method will perform the following checks in order:
+   * <br><ul>
+   *     <li>Checks if Object equals the class. Returns true when equal and continues otherwise</li>
+   *     <li>Checks if the Object is an instance of a PlaceholderExpansion. Returns false if not</li>
+   *     <li>Checks if the Object's Identifier, Author and version equal the one of this class</li>
+   * </ul>
+   * 
+   * @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) {
@@ -226,7 +322,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(),