SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
paper-api/src/main/java/org/bukkit/help/GenericCommandHelpTopic.java
View File

@@ -10,9 +10,10 @@ import org.bukkit.command.defaults.VanillaCommand;
import org.bukkit.help.HelpTopic;
/**
* Lacking an alternative, the help system will create instances of GenericCommandHelpTopic for each command in the
* server's CommandMap. You can use this class as a base class for custom help topics, or as an example for how to
* write your own.
* Lacking an alternative, the help system will create instances of
* GenericCommandHelpTopic for each command in the server's CommandMap. You
* can use this class as a base class for custom help topics, or as an example
* for how to write your own.
*/
public class GenericCommandHelpTopic extends HelpTopic {

55
paper-api/src/main/java/org/bukkit/help/HelpMap.java
View File

@@ -4,20 +4,25 @@ import java.util.Collection;
import java.util.List;
/**
* The HelpMap tracks all help topics registered in a Bukkit server. When the server starts up or is reloaded,
* help is processed and topics are added in the following order:
* <p/>
* 1. General topics are loaded from the help.yml
* 2. Plugins load and optionally call {@code addTopic()}
* 3. Registered plugin commands are processed by {@link HelpTopicFactory} objects to create topics
* 4. Topic contents are amended as directed in help.yml
* The HelpMap tracks all help topics registered in a Bukkit server. When the
* server starts up or is reloaded, help is processed and topics are added in
* the following order:
* <p>
* <ol>
* <li>General topics are loaded from the help.yml
* <li>Plugins load and optionally call {@code addTopic()}
* <li>Registered plugin commands are processed by {@link HelpTopicFactory}
* objects to create topics
* <li>Topic contents are amended as directed in help.yml
* </ol>
*/
public interface HelpMap {
/**
* Returns a help topic for a given topic name.
*
* @param topicName The help topic name to look up.
* @return A {@link HelpTopic} object matching the topic name or null if none can be found.
* @return A {@link HelpTopic} object matching the topic name or null if
* none can be found.
*/
public HelpTopic getHelpTopic(String topicName);
@@ -36,28 +41,36 @@ public interface HelpMap {
public void addTopic(HelpTopic topic);
/**
* Clears out the contents of the help index. Normally called during server reload.
* Clears out the contents of the help index. Normally called during
* server reload.
*/
public void clear();
/**
* Associates a {@link HelpTopicFactory} object with given command base class. Plugins typically
* call this method during {@code onLoad()}. Once registered, the custom HelpTopicFactory will
* be used to create a custom {@link HelpTopic} for all commands deriving from the {@code commandClass}
* base class, or all commands deriving from {@link org.bukkit.command.PluginCommand} who's executor
* derives from {@code commandClass} base class.
* Associates a {@link HelpTopicFactory} object with given command base
* class. Plugins typically call this method during {@code onLoad()}. Once
* registered, the custom HelpTopicFactory will be used to create a custom
* {@link HelpTopic} for all commands deriving from the {@code
* commandClass} base class, or all commands deriving from {@link
* org.bukkit.command.PluginCommand} who's executor derives from {@code
* commandClass} base class.
*
* @param commandClass The class for which the custom HelpTopicFactory applies. Must derive from
* either {@link org.bukkit.command.Command} or {@link org.bukkit.command.CommandExecutor}.
* @param factory The {@link HelpTopicFactory} implementation to associate with the {@code commandClass}.
* @throws IllegalArgumentException Thrown if {@code commandClass} does not derive from a legal base class.
* @param commandClass The class for which the custom HelpTopicFactory
* applies. Must derive from either {@link org.bukkit.command.Command}
* or {@link org.bukkit.command.CommandExecutor}.
* @param factory The {@link HelpTopicFactory} implementation to associate
* with the {@code commandClass}.
* @throws IllegalArgumentException Thrown if {@code commandClass} does
* not derive from a legal base class.
*/
public void registerHelpTopicFactory(Class<?> commandClass, HelpTopicFactory<?> factory);
/**
* Gets the list of plugins the server administrator has chosen to exclude from the help index. Plugin authors
* who choose to directly extend {@link org.bukkit.command.Command} instead of {@link org.bukkit.command.PluginCommand}
* will need to check this collection in their {@link HelpTopicFactory} implementations to ensure they meet the
* Gets the list of plugins the server administrator has chosen to exclude
* from the help index. Plugin authors who choose to directly extend
* {@link org.bukkit.command.Command} instead of {@link
* org.bukkit.command.PluginCommand} will need to check this collection in
* their {@link HelpTopicFactory} implementations to ensure they meet the
* server administrator's expectations.
*
* @return A list of plugins that should be excluded from the help index.

67
paper-api/src/main/java/org/bukkit/help/HelpTopic.java
View File

@@ -4,14 +4,16 @@ import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
/**
* HelpTopic implementations are displayed to the user when the user uses the /help command.
* HelpTopic implementations are displayed to the user when the user uses the
* /help command.
* <p>
* Custom implementations of this class can work at two levels. A simple implementation only
* needs to set the value of {@code name}, {@code shortText}, and {@code fullText} int the
* constructor. This base class will take care of the rest.
* Custom implementations of this class can work at two levels. A simple
* implementation only needs to set the value of {@code name}, {@code
* shortText}, and {@code fullText} in the constructor. This base class will
* take care of the rest.
* <p>
* Complex implementations can be created by overriding the behavior of all the methods in
* this class.
* Complex implementations can be created by overriding the behavior of all
* the methods in this class.
*/
public abstract class HelpTopic {
protected String name;
@@ -20,8 +22,10 @@ public abstract class HelpTopic {
protected String amendedPermission;
/**
* Determines if a {@link Player} is allowed to see this help topic. HelpTopic implementations should take
* server administrator wishes into account as set by the {@link HelpTopic#amendCanSee(String)} function.
* Determines if a {@link Player} is allowed to see this help topic.
* <p>
* HelpTopic implementations should take server administrator wishes into
* account as set by the {@link HelpTopic#amendCanSee(String)} function.
*
* @param player The Player in question.
* @return True of the Player can see this help topic, false otherwise.
@@ -29,11 +33,15 @@ public abstract class HelpTopic {
public abstract boolean canSee(CommandSender player);
/**
* Allows the server administrator to override the permission required to see a help topic. HelpTopic
* implementations should take this into account when determining topic visibility on the
* {@link HelpTopic#canSee(org.bukkit.command.CommandSender)} function.
* Allows the server administrator to override the permission required to
* see a help topic.
* <p>
* HelpTopic implementations should take this into account when
* determining topic visibility on the {@link
* HelpTopic#canSee(org.bukkit.command.CommandSender)} function.
*
* @param amendedPermission The permission node the server administrator wishes to apply to this topic.
* @param amendedPermission The permission node the server administrator
* wishes to apply to this topic.
*/
public void amendCanSee(String amendedPermission) {
this.amendedPermission = amendedPermission;
@@ -58,11 +66,14 @@ public abstract class HelpTopic {
}
/**
* Returns the full description of this help topic that is displayed when the user requests this topic's details.
* Returns the full description of this help topic that is displayed when
* the user requests this topic's details.
* <p>
* The result will be paginated to properly fit the user's client.
*
* @param forWho The player or console requesting the full text. Useful for further security trimming
* the command's full text based on sub-permissions in custom implementations.
* @param forWho The player or console requesting the full text. Useful
* for further security trimming the command's full text based on
* sub-permissions in custom implementations.
*
* @return A full topic description.
*/
@@ -71,13 +82,18 @@ public abstract class HelpTopic {
}
/**
* Allows the server admin (or another plugin) to add or replace the contents of a help topic. A null in
* either parameter will leave that part of the topic unchanged. In either amending parameter, the string
* {@literal <text>} is replaced with the existing contents in the help topic. Use this to append or prepend
* additional content into an automatically generated help topic.
* Allows the server admin (or another plugin) to add or replace the
* contents of a help topic.
* <p>
* A null in either parameter will leave that part of the topic unchanged.
* In either amending parameter, the string {@literal <text>} is replaced
* with the existing contents in the help topic. Use this to append or
* prepend additional content into an automatically generated help topic.
*
* @param amendedShortText The new topic short text to use, or null to leave alone.
* @param amendedFullText The new topic full text to use, or null to leave alone.
* @param amendedShortText The new topic short text to use, or null to
* leave alone.
* @param amendedFullText The new topic full text to use, or null to leave
* alone.
*/
public void amendTopic(String amendedShortText, String amendedFullText) {
shortText = applyAmendment(shortText, amendedShortText);
@@ -85,14 +101,15 @@ public abstract class HelpTopic {
}
/**
* Developers implementing their own custom HelpTopic implementations can use this utility method to ensure
* their implementations comply with the expected behavior of the {@link HelpTopic#amendTopic(String, String)}
* Developers implementing their own custom HelpTopic implementations can
* use this utility method to ensure their implementations comply with the
* expected behavior of the {@link HelpTopic#amendTopic(String, String)}
* method.
*
* @param baseText The existing text of the help topic.
* @param amendment The amending text from the amendTopic() method.
* @return The application of the amending text to the existing text, according to the expected rules of
* amendTopic().
* @return The application of the amending text to the existing text,
* according to the expected rules of amendTopic().
*/
protected String applyAmendment(String baseText, String amendment) {
if (amendment == null) {

6
paper-api/src/main/java/org/bukkit/help/HelpTopicComparator.java
View File

@@ -5,8 +5,10 @@ import org.bukkit.help.HelpTopic;
import java.util.Comparator;
/**
* Used to impose a custom total ordering on help topics. All topics are listed in alphabetic order, but topics
* that start with a slash come after topics that don't.
* Used to impose a custom total ordering on help topics.
* <p>
* All topics are listed in alphabetic order, but topics that start with a
* slash come after topics that don't.
*/
public class HelpTopicComparator implements Comparator<HelpTopic> {

42
paper-api/src/main/java/org/bukkit/help/HelpTopicFactory.java
View File

@@ -3,32 +3,40 @@ package org.bukkit.help;
import org.bukkit.command.Command;
/**
* A HelpTopicFactory is used to create custom {@link HelpTopic} objects from commands that inherit from a
* common base class or have executors that inherit from a common base class. You can use a custom HelpTopic to change
* the way all the commands in your plugin display in the help. If your plugin implements a complex permissions system,
* a custom help topic may also be appropriate.
* A HelpTopicFactory is used to create custom {@link HelpTopic} objects from
* commands that inherit from a common base class or have executors that
* inherit from a common base class. You can use a custom HelpTopic to change
* the way all the commands in your plugin display in the help. If your plugin
* implements a complex permissions system, a custom help topic may also be
* appropriate.
* <p>
* To automatically bind your plugin's commands to your custom HelpTopic implementation, first make sure all your
* commands or executors derive from a custom base class (it doesn't have to do anything). Next implement a custom
* HelpTopicFactory that accepts your custom command base class and instantiates an instance of your custom HelpTopic
* from it. Finally, register your HelpTopicFactory against your command base class using the {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)}
* method.
* To automatically bind your plugin's commands to your custom HelpTopic
* implementation, first make sure all your commands or executors derive from
* a custom base class (it doesn't have to do anything). Next implement a
* custom HelpTopicFactory that accepts your custom command base class and
* instantiates an instance of your custom HelpTopic from it. Finally,
* register your HelpTopicFactory against your command base class using the
* {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)} method.
* <p>
* As the help system iterates over all registered commands to make help topics, it first checks to see if there is a
* HelpTopicFactory registered for the command's base class. If so, the factory is used to make a help topic rather
* than a generic help topic. If no factory is found for the command's base class and the command derives from
* {@link org.bukkit.command.PluginCommand}, then the type of the command's executor is inspected looking for a registered
* HelpTopicFactory. Finally, if no factory is found, a generic help topic is created for the command.
* As the help system iterates over all registered commands to make help
* topics, it first checks to see if there is a HelpTopicFactory registered
* for the command's base class. If so, the factory is used to make a help
* topic rather than a generic help topic. If no factory is found for the
* command's base class and the command derives from {@link
* org.bukkit.command.PluginCommand}, then the type of the command's executor
* is inspected looking for a registered HelpTopicFactory. Finally, if no
* factory is found, a generic help topic is created for the command.
*
* @param <TCommand> The base class for your custom commands.
*/
public interface HelpTopicFactory<TCommand extends Command> {
/**
* This method accepts a command deriving from a custom command base class and constructs a custom HelpTopic
* for it.
* This method accepts a command deriving from a custom command base class
* and constructs a custom HelpTopic for it.
*
* @param command The custom command to build a help topic for.
* @return A new custom help topic or {@code null} to intentionally NOT create a topic.
* @return A new custom help topic or {@code null} to intentionally NOT
* create a topic.
*/
public HelpTopic createTopic(TCommand command);
}

17
paper-api/src/main/java/org/bukkit/help/IndexHelpTopic.java
View File

@@ -9,11 +9,12 @@ import org.bukkit.util.ChatPaginator;
import java.util.Collection;
/**
* This help topic generates a list of other help topics. This class is useful for adding your own
* index help topics. To enforce a particular order, use a sorted collection.
* <p/>
* If a preamble is provided to the constructor, that text will be displayed before the first item
* in the index.
* This help topic generates a list of other help topics. This class is useful
* for adding your own index help topics. To enforce a particular order, use a
* sorted collection.
* <p>
* If a preamble is provided to the constructor, that text will be displayed
* before the first item in the index.
*/
public class IndexHelpTopic extends HelpTopic {
@@ -81,7 +82,8 @@ public class IndexHelpTopic extends HelpTopic {
}
/**
* Builds the topic preamble. Override this method to change how the index preamble looks.
* Builds the topic preamble. Override this method to change how the index
* preamble looks.
*
* @param sender The command sender requesting the preamble.
* @return The topic preamble.
@@ -91,7 +93,8 @@ public class IndexHelpTopic extends HelpTopic {
}
/**
* Builds individual lines in the index topic. Override this method to change how index lines are rendered.
* Builds individual lines in the index topic. Override this method to
* change how index lines are rendered.
*
* @param sender The command sender requesting the index line.
* @param topic The topic to render into an index line.