Move parsing method to PlaceholderExpansion

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

@@ -25,8 +25,22 @@ import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+@Deprecated
 public abstract class PlaceholderHook {
+
+  /**
+   * Please see {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(OfflinePlayer, String) PlaceholderExpansion#parsePlaceholder(OfflinePlayer, String)}
+   * for a full description of what this method is used for.
+   * 
+   * @param player Possibly-null OfflinePlayer instance to use.
+   * @param params String after {@code %<expansion>_} and before the second percent symbol.
+   * @return Possibly-null String depending on the Expansions returned value.
+   * @deprecated Planned for removal in 2.14.0
+   *             <br>Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(OfflinePlayer, String) parsePlaceholders(OfflinePlayer, String)}
+   *             instead
+   */
   @Nullable
+  @Deprecated
   public String onRequest(final OfflinePlayer player, @NotNull final String params) {
     if (player != null && player.isOnline()) {
       return onPlaceholderRequest((Player) player, params);
@@ -35,7 +49,20 @@ public abstract class PlaceholderHook {
     return onPlaceholderRequest(null, params);
   }
 
+  /**
+   * Please see {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(Player, String) PlaceholderExpansion#parsePlaceholder(Player, String)}
+   * for a full description of what this method is used for.
+   *
+   * @param player Possibly-null Player instance to use.
+   * @param params String after {@code %<expansion>_} and before the second percent symbol.
+   * @return Possibly-null String depending on the Expansions returned value.
+   * 
+   * @deprecated Planned for removal in 2.14.0
+   *             <br>Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(Player, String) parsePlaceholders(Player, String)}
+   *             instead
+   */
   @Nullable
+  @Deprecated
   public String onPlaceholderRequest(final Player player, @NotNull final String params) {
     return null;
   }

src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java

@@ -26,7 +26,9 @@ import java.util.logging.Level;
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import me.clip.placeholderapi.PlaceholderHook;
 import org.bukkit.Bukkit;
+import org.bukkit.OfflinePlayer;
 import org.bukkit.configuration.ConfigurationSection;
+import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
@@ -398,6 +400,45 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
         getAuthor(), getVersion());
   }
 
+  /**
+   * PlaceholderAPI will call this method whenever a valid placeholder pattern with a matching
+   * PlaceholderExpansion is found.
+   * <br>The provided Player can be one of 3 possible states:
+   * 
+   * <ul>
+   *   <li>Not null and online</li>
+   *   <li>Not null and offline</li>
+   *   <li>Null</li>
+   * </ul>
+   * 
+   * By default will PlaceholderAPI check if the OfflinePlayer is both not null and online.
+   * <br>If both checks return true will it call {@link #parsePlaceholders(Player, String) parsePlaceholder(Player, String)}
+   * with the provided OfflinePlayer casted to a Player. Otherwise will the same method be called,
+   * but with {@code null} as Player value.
+   * 
+   * <p>To use this method in your PlaceholderExpansion, override it.
+   * 
+   * <p>When {@code null} is returned will PlaceholderAPI see this as "invalid placeholder" and
+   * return the placeholder as-is in the final String.
+   * 
+   * @param player The OfflinePlayer to use.
+   * @param params The params from {@code %<expansion>_<params>%}
+   * @return Parsed placeholder, or null, depending on the Expansion's handling of it.
+   */
+  @Nullable
+  public String parsePlaceholders(OfflinePlayer player, String params) {
+    if (player != null && player.isOnline()) {
+      this.onPlaceholderRequest((Player) player, params);
+    }
+    
+    return parsePlaceholders(null, params);
+  }
+  
+  @Nullable
+  public String parsePlaceholders(Player player, String params){
+    return this.onRequest(player, params);
+  }
+  
   // === Deprecated API ===
 
   /**

src/main/java/me/clip/placeholderapi/expansion/Relational.java

@@ -21,23 +21,29 @@
 package me.clip.placeholderapi.expansion;
 
 import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
- * Implementing this interface allows your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
- * to be used as a relational placeholder expansion.
+ * This interface should be used when your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
+ * should support relational placeholders.
  * 
- * <p>Relational placeholders take two Players as input and are always prefixed with {@code rel_},
- * so {@code %foo_bar%} becomes {@code %rel_foo_bar%}
+ * <p>The difference between relational placeholders and normal ones is, that relational ones start
+ * with a {@code rel_} prefix and have two Players provided, instead of one.
+ * <br>The main purpose is to return a String based on the "relationship" between the two players
+ * (i.e. if both are within the same world).
  */
 public interface Relational {
 
   /**
-   * This method is called whenever a placeholder starting with {@code rel_} is called.
+   * This method will be called whenever a valid placeholder in the format {@code %rel_<expansion>_<identifier>%}
+   * is found.
    * 
-   * @param one The first player used for the placeholder.
-   * @param two The second player used for the placeholder.
-   * @param identifier The text right after the expansion's name (%expansion_<b>identifier</b>%)
-   * @return Parsed String from the expansion.
+   * @param one The first player to use for comparison.
+   * @param two The second player to use for comparison
+   * @param identifier String right after {@code %rel_<expansion>_} and before the second percent symbol.
+   * @return Possibly-null String, depending on what the expansion returns.
    */
-  String onPlaceholderRequest(Player one, Player two, String identifier);
+  @Nullable
+  String onPlaceholderRequest(Player one, Player two, @NotNull String identifier);
 }

src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java

@@ -116,7 +116,7 @@ public final class CharsReplacer implements Replacer {
         continue;
       }
 
-      final String replacement = placeholder.onRequest(player, parametersString);
+      final String replacement = placeholder.parsePlaceholders(player, parametersString);
       if (replacement == null) {
         builder.append(closure.head).append(identifierString);
 

src/main/java/me/clip/placeholderapi/replacer/RegexReplacer.java

@@ -61,7 +61,7 @@ public final class RegexReplacer implements Replacer {
         continue;
       }
 
-      final String requested = expansion.onRequest(player, parameters);
+      final String requested = expansion.parsePlaceholders(player, parameters);
       matcher.appendReplacement(builder, requested != null ? requested : matcher.group(0));
     }
     while (matcher.find());