[Wiki] Move on(Placeholder)Request into code annotations

docs/developers/creating-a-placeholderexpansion.md

@@ -45,52 +45,66 @@ import me.clip.placeholderapi.expansion.PlaceholderExpansion;
 public class SomeExpansion extends PlaceholderExpansion {
     
     @Override
+    @NotNull
     public String getAuthor() {
         return "Author"; // (1)
     }
     
     @Override
+    @NotNull
     public String getIdentifier() {
         return "example"; // (2)
     }
     
     @Override
+    @NotNull
     public String getVersion() {
         return "1.0.0"; // (3)
     }
+
+    // These methods aren't overriden by default.
+    // You have to override one of them.
+    
+    @Override
+    public String onRequest(OfflinePlayer player, @NotNull String identifier) {
+        // (4)
+    }
+    
+    @Override
+    public String onPlaceholderRequest(Player player, @NotNull String identifier) {
+        // (5)
+    }
 }
 ```
 
-1.  This method allows you to set the name of the expansion's author.
+1.  This method allows you to set the name of the expansion's author. May not be null.
 
-2.  The identifier is the part in the placeholder that is between the first `%` (or `{` if bracket placeholders are used) and the first `_`.  
-    The identifier may not contain `%`, `{`, `}` or `_`.
+2.  The identifier is the part in the placeholder that is between the first `%` (or `{` for bracket placeholders) and the first `_`.  
+    The identifier may not be null nor contain `%`, `{`, `}` or `_`.
     
     If you still want to use them in your expansion name, override the `getName()` method.
 
-3.  This method returns the version of the expansion.  
+3.  This method returns the version of the expansion. May not be null.  
     Due to it being a string are you not limited to numbers alone, but it is recommended to stick with a number pattern.
     
     PlaceholderAPI uses this String to compare with the latest version on the eCloud (if uploaded to it) to see if a new version is available.  
     If your expansion is included in a plugin, this does not matter.
 
-You must also choose between one of these two methods for handling the actual parsing of placeholders (Exception being expansions providing [relational placeholders](#making-a-relational-expansion)):
+4.  The first parameter is the Player that the placeholders are parsed against, given as an nullable OfflinePlayer instance.  
+    The second parameter is a non-null String representing the content of the placeholder *after* the first `_` and before the closing `%` (or `}` for bracket placeholders).
 
-- `onRequest(OfflinePlayer, String)`  
-    The first parameter is the player that the placeholders are parsed against, given as an OfflinePlayer instance. This can be null.  
-    The second parameter is the content of the placeholder after the first `_` and before the closing `%` (or `}` if bracket placeholders are used). This String is never null.
+    PlaceholderAPI calls this method first!  
+    If not explicitly overriden, this method will forward to `onPlaceholderRequest(Player, String)`, converting the OfflinePlayer to a Player if possible or otherwise providing null.
+    Using this method is recommended as its usage of an OfflinePlayer is allowing the parsing of placeholders without the playing having to be online for certain data, such as their UUID.
 
-    If not explicity overriden, this will automatically call `onPlaceholderRequest(Player, String)`, passing the parameters as-is to it.  
-    This method is recommended as it allows the usage of offline players, meaning the player does not need to be online to obtain certain certain data from them such as name or UUID.
+5.  The first parameter is the Player that the placeholders are parsed against, given as a nullable Player instance.
+    The second parameter is a non-null String representing the content of the placeholder *after* the first `_` and before the closing `%` (or `}` for bracket placeholders).
 
-- `onPlaceholderRequest(Player, String)`  
-    The first parameter is the player that the placeholders are parsed against, given as a Player instance. This can be null.  
-    The second parameter is the content of the placeholder after the first `_` and before the closing `%` (or `}` if bracket placeholders are used). This String is never null.
-    
-    If not set, this method will return `null` which PlaceholderAPI sees as an invalid placeholder.
+    This method is called by `onRequest(OfflinePlayer, String)` if said method isn't overriden.
+    If not set itself, this method will return `null` which PlaceholderAPI understands as an invalid placeholder.
 
 /// note
-PlaceholderAPI always calls `onRequest(Player, String)` in a PlaceholderExpansion.
+Overriding `onRequest(OfflinePlayer, String)` or `onPlaceholderRequest(Player, String)` is not required if you [create relational placeholders](#making-a-relational-expansion).
 ///
 
 ----