Merge pull request #512 from PlaceholderAPI/fix/javadoc-build-errors

Fix Javadoc build errors
2025-09-05 17:07:06 +02:00 · 2020-12-14 08:54:27 +08:00
parent a3d6426084 59cd5982ad
commit 4074192c0b
5 changed files with 111 additions and 18 deletions
--- a/build.gradle
+++ b/build.gradle
@@ -49,6 +49,10 @@ tasks.withType(JavaCompile) {
    options.encoding = "UTF-8"
 }

+javadoc {
+    options.encoding = "UTF-8"
+}
+
 shadowJar {
    archiveClassifier.set("")

--- a/src/main/java/me/clip/placeholderapi/PlaceholderAPI.java
+++ b/src/main/java/me/clip/placeholderapi/PlaceholderAPI.java
@@ -29,6 +29,7 @@ import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import me.clip.placeholderapi.expansion.PlaceholderExpansion;
 import me.clip.placeholderapi.expansion.Relational;
+import me.clip.placeholderapi.expansion.manager.LocalExpansionManager;
 import me.clip.placeholderapi.replacer.CharsReplacer;
 import me.clip.placeholderapi.replacer.Replacer;
 import me.clip.placeholderapi.replacer.Replacer.Closure;
@@ -150,7 +151,7 @@ public final class PlaceholderAPI {

  /**
   * set relational placeholders in the text specified placeholders are matched with the pattern
-   * %<rel_(identifier)_(params)>% when set with this method
+   * {@literal %<rel_(identifier)_(params)>%} when set with this method
   *
   * @param one First player to compare
   * @param two Second player to compare
@@ -225,6 +226,8 @@ public final class PlaceholderAPI {

  /**
   * Get the normal placeholder pattern.
+   *
+   * @return The default Placeholder Pattern
   */
  public static Pattern getPlaceholderPattern() {
    return PLACEHOLDER_PATTERN;
@@ -232,6 +235,8 @@ public final class PlaceholderAPI {

  /**
   * Get the bracket placeholder pattern.
+   *
+   * @return the Bracket Placeholder Pattern
   */
  public static Pattern getBracketPlaceholderPattern() {
    return BRACKET_PLACEHOLDER_PATTERN;
@@ -239,6 +244,8 @@ public final class PlaceholderAPI {

  /**
   * Get the relational placeholder pattern.
+   *
+   * @return The Relational Placeholder Pattern
   */
  public static Pattern getRelationalPlaceholderPattern() {
    return RELATIONAL_PLACEHOLDER_PATTERN;
@@ -284,10 +291,10 @@ public final class PlaceholderAPI {

  /**
   * Get map of registered placeholders
+   * 
+   * @deprecated Use {@link LocalExpansionManager#getExpansions()} instead.
   *
   * @return Map of registered placeholders
-   * @deprecated Use {@link me.clip.placeholderapi.PlaceholderAPIPlugin().getLocalExpansionManager()
-   * .getExpansions()} instead.
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -298,8 +305,12 @@ public final class PlaceholderAPI {
  }

  /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
   * register placeholders instead
+   * 
+   * @param plugin The Plugin to register with this {@link PlaceholderHook}
+   * @param placeholderHook The {@link PlaceholderHook} to register
+   * @return always false
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -312,8 +323,12 @@ public final class PlaceholderAPI {
  }

  /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
   * register placeholders instead
+   * 
+   * @param identifier The identifier to use for the {@link PlaceholderHook}
+   * @param placeholderHook The {@link PlaceholderHook} to register
+   * @return always false
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -325,8 +340,11 @@ public final class PlaceholderAPI {
  }

  /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
   * unregister placeholders instead
+   * 
+   * @param plugin The plugin to unregister
+   * @return always false
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -339,8 +357,11 @@ public final class PlaceholderAPI {
  }

  /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
   * unregister placeholders instead
+   * 
+   * @param identifier The identifier to unregister
+   * @return always false
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -352,6 +373,8 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Will be removed in a future release.
+   * 
+   * @return Set of registered identifiers
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -361,6 +384,8 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Will be removed in a future release.
+   * 
+   * @return always null
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -370,6 +395,12 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, String)} instead
+   * 
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param pattern The Pattern to use
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -380,6 +411,12 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, List)} instead
+   * 
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param pattern The Pattern to use
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -390,6 +427,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -400,6 +442,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param pattern The Pattern to use
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -409,6 +456,11 @@ public final class PlaceholderAPI {
  }
  /**
   * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -418,6 +470,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -427,6 +484,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -436,6 +498,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param pattern The Pattern to use
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -445,6 +512,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -455,6 +527,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -464,6 +541,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -473,6 +555,11 @@ public final class PlaceholderAPI {

  /**
   * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -483,12 +570,12 @@ public final class PlaceholderAPI {

  /**
   * set relational placeholders in the text specified placeholders are matched with the pattern
-   * %<rel_(identifier)_(params)>% when set with this method
+   * {@literal %<rel_(identifier)_(params)>%} when set with this method
   *
   * @param one Player to compare
   * @param two Player to compare
   * @param text Text to parse the placeholders in
-   * @param colorize If color codes (&[0-1a-fk-o]) should be translated
+   * @param colorize If color codes ({@literal &[0-1a-fk-o]}) should be translated
   * @return The text containing the parsed relational placeholders
   * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
   */
@@ -506,9 +593,9 @@ public final class PlaceholderAPI {
   * @param one First player to compare
   * @param two Second player to compare
   * @param text Text to parse the placeholders in
-   * @param colorize If color codes (&[0-1a-fk-o]) should be translated
+   * @param colorize If color codes ({@literal &[0-1a-fk-o]}) should be translated
   * @return The text containing the parsed relational placeholders
-   * @deprecated Use {@link #setRelationalPlaceholders(Player, Player, List<String>)} instead.
+   * @deprecated Use {@link #setRelationalPlaceholders(Player, Player, List)} instead.
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
--- a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java
@@ -237,6 +237,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {

  /**
   * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()}
+   *
+   * @return The plugin name.
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -246,6 +248,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {

  /**
   * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description
+   *
+   * @return The description of the expansion.
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -255,6 +259,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {

  /**
   * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link
+   *
+   * @return The link for the expansion.
   */
  @Deprecated
  @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
--- a/src/main/java/me/clip/placeholderapi/expansion/VersionSpecific.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/VersionSpecific.java
@@ -34,6 +34,8 @@ public interface VersionSpecific {
   * This method is called before the expansion is attempted to be registered The server version
   * will be passed to this method so you know what version the server is currently running.
   *
+   * @param v The {@link Version} to check against
+   *
   * @return true if your expansion is compatible with the version the server is running.
   */
  boolean isCompatibleWith(Version v);
--- a/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java
@@ -174,10 +174,7 @@ public final class LocalExpansionManager implements Listener {

    return Optional.empty();
  }
-
-  /**
-   * Do not call this method yourself, use {@link PlaceholderExpansion#register()}
-   */
+  
  @ApiStatus.Internal
  public boolean register(@NotNull final PlaceholderExpansion expansion) {
    final String identifier = expansion.getIdentifier().toLowerCase();
@@ -271,9 +268,6 @@ public final class LocalExpansionManager implements Listener {
    return true;
  }

-  /**
-   * Do not call this method yourself, use {@link PlaceholderExpansion#unregister()}
-   */
  @ApiStatus.Internal
  public boolean unregister(@NotNull final PlaceholderExpansion expansion) {
    if (expansions.remove(expansion.getIdentifier()) == null) {