Pulling all pending Bukkit-JavaDoc changes

By: Wesley Wolfe <weswolf@aol.com>

paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java

@@ -10,8 +10,41 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
 /**
- * Called early in the command handling process. This event is only
- * for very exceptional cases and you should not normally use it.
+ * This event is called whenever a player runs a command (by placing a slash
+ * at the start of their message). It is called early in the command handling
+ * process, and modifications in this event (via {@link #setMessage(String)})
+ * will be shown in the behavior.
+ * <p>
+ * Many plugins will have <b>no use for this event</b>, and you should
+ * attempt to avoid using it if it is not necessary.
+ * <p>
+ * Some examples of valid uses for this event are:
+ * <ul>
+ * <li>Logging executed commands to a separate file
+ * <li>Variable substitution. For example, replacing
+ *     <code>${nearbyPlayer}</code> with the name of the nearest other
+ *     player, or simulating the <code>@a</code> and <code>@p</code>
+ *     decorators used by Command Blocks in plugins that do not handle it.
+ * <li>Conditionally blocking commands belonging to other plugins. For
+ *     example, blocking the use of the <code>/home</code> command in a
+ *     combat arena.
+ * <li>Per-sender command aliases. For example, after a player runs the
+ *     command <code>/calias cr gamemode creative</code>, the next time they
+ *     run <code>/cr</code>, it gets replaced into
+ *     <code>/gamemode creative</code>. (Global command aliases should be
+ *     done by registering the alias.)
+ * </ul>
+ * <p>
+ * Examples of incorrect uses are:
+ * <ul>
+ * <li>Using this event to run command logic
+ * </ul>
+ * <p>
+ * If the event is cancelled, processing of the command will halt.
+ * <p>
+ * The state of whether or not there is a slash (<code>/</code>) at the
+ * beginning of the message should be preserved. If a slash is added or
+ * removed, unexpected behavior may result.
  */
 public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();