Pulling all pending Bukkit-JavaDoc changes

By: Edmond Poon <sagaciouszzzz@gmail.com>

paper-api/src/main/java/org/bukkit/conversations/BooleanPrompt.java

@@ -25,6 +25,7 @@ public abstract class BooleanPrompt extends ValidatingPrompt{
 
     /**
      * Override this method to perform some action with the user's boolean response.
+     *
      * @param context Context information about the conversation.
      * @param input The user's boolean response.
      * @return The next {@link Prompt} in the prompt graph.

paper-api/src/main/java/org/bukkit/conversations/Conversable.java

@@ -9,6 +9,7 @@ public interface Conversable {
 
     /**
      * Tests to see of a Conversable object is actively engaged in a conversation.
+     *
      * @return True if a conversation is in progress
      */
     public boolean isConversing();
@@ -16,12 +17,14 @@ public interface Conversable {
     /**
      * Accepts input into the active conversation. If no conversation is in progress,
      * this method does nothing.
+     *
      * @param input The input message into the conversation
      */
     public void acceptConversationInput(String input);
 
     /**
      * Enters into a dialog with a Conversation object.
+     *
      * @param conversation The conversation to begin
      * @return True if the conversation should proceed, false if it has been enqueued
      */
@@ -29,12 +32,14 @@ public interface Conversable {
 
     /**
      * Abandons an active conversation.
+     *
      * @param conversation The conversation to abandon
      */
     public void abandonConversation(Conversation conversation);
 
     /**
      * Abandons an active conversation.
+     *
      * @param conversation The conversation to abandon
      * @param details Details about why the conversation was abandoned
      */

paper-api/src/main/java/org/bukkit/conversations/Conversation.java

@@ -11,18 +11,18 @@ import java.util.Map;
  * The Conversation class is responsible for tracking the current state of a conversation, displaying prompts to
  * the user, and dispatching the user's response to the appropriate place. Conversation objects are not typically
  * instantiated directly. Instead a {@link ConversationFactory} is used to construct identical conversations on demand.
- *
+ * <p>
  * Conversation flow consists of a directed graph of {@link Prompt} objects. Each time a prompt gets input from the
  * user, it must return the next prompt in the graph. Since each Prompt chooses the next Prompt, complex conversation
  * trees can be implemented where the nature of the player's response directs the flow of the conversation.
- *
+ * <p>
  * Each conversation has a {@link ConversationPrefix} that prepends all output from the conversation to the player.
  * The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves.
- *
+ * <p>
  * Each conversation has a timeout measured in the number of inactive seconds to wait before abandoning the conversation.
  * If the inactivity timeout is reached, the conversation is abandoned and the user's incoming and outgoing chat is
  * returned to normal.
- *
+ * <p>
  * You should not construct a conversation manually. Instead, use the {@link ConversationFactory} for access to all
  * available options.
  */
@@ -40,6 +40,7 @@ public class Conversation {
 
     /**
      * Initializes a new Conversation.
+     *
      * @param plugin The plugin that owns this conversation.
      * @param forWhom The entity for whom this conversation is mediating.
      * @param firstPrompt The first prompt in the conversation graph.
@@ -50,6 +51,7 @@ public class Conversation {
 
     /**
      * Initializes a new Conversation.
+     *
      * @param plugin The plugin that owns this conversation.
      * @param forWhom The entity for whom this conversation is mediating.
      * @param firstPrompt The first prompt in the conversation graph.
@@ -67,6 +69,7 @@ public class Conversation {
 
     /**
      * Gets the entity for whom this conversation is mediating.
+     *
      * @return The entity.
      */
     public Conversable getForWhom() {
@@ -76,6 +79,7 @@ public class Conversation {
     /**
      * Gets the modality of this conversation. If a conversation is modal, all messages directed to the player
      * are suppressed for the duration of the conversation.
+     *
      * @return The conversation modality.
      */
     public boolean isModal() {
@@ -85,6 +89,7 @@ public class Conversation {
     /**
      * Sets the modality of this conversation.  If a conversation is modal, all messages directed to the player
      * are suppressed for the duration of the conversation.
+     *
      * @param modal The new conversation modality.
      */
     void setModal(boolean modal) {
@@ -94,6 +99,7 @@ public class Conversation {
     /**
      * Gets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation
      * gets echoed back into the submitter's chat window.
+     *
      * @return The status of local echo.
      */
     public boolean isLocalEchoEnabled() {
@@ -103,6 +109,7 @@ public class Conversation {
     /**
      * Sets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation
      * gets echoed back into the submitter's chat window.
+     *
      * @param localEchoEnabled The status of local echo.
      */
     public void setLocalEchoEnabled(boolean localEchoEnabled) {
@@ -111,6 +118,7 @@ public class Conversation {
 
     /**
      * Gets the {@link ConversationPrefix} that prepends all output from this conversation.
+     *
      * @return The ConversationPrefix in use.
      */
     public ConversationPrefix getPrefix() {
@@ -119,6 +127,7 @@ public class Conversation {
 
     /**
      * Sets the {@link ConversationPrefix} that prepends all output from this conversation.
+     *
      * @param prefix The ConversationPrefix to use.
      */
     void setPrefix(ConversationPrefix prefix) {
@@ -127,6 +136,7 @@ public class Conversation {
 
     /**
      * Adds a {@link ConversationCanceller} to the cancellers collection.
+     *
      * @param canceller The {@link ConversationCanceller} to add.
      */
     void addConversationCanceller(ConversationCanceller canceller) {
@@ -136,6 +146,7 @@ public class Conversation {
 
     /**
      * Gets the list of {@link ConversationCanceller}s
+     *
      * @return The list.
      */
     public List<ConversationCanceller> getCancellers() {
@@ -144,6 +155,7 @@ public class Conversation {
 
     /**
      * Returns the Conversation's {@link ConversationContext}.
+     *
      * @return The ConversationContext.
      */
     public ConversationContext getContext() {

paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java

@@ -22,6 +22,7 @@ public class ConversationAbandonedEvent extends EventObject {
 
     /**
      * Gets the object that caused the conversation to be abandoned.
+     *
      * @return The object that abandoned the conversation.
      */
     public ConversationCanceller getCanceller() {
@@ -30,6 +31,7 @@ public class ConversationAbandonedEvent extends EventObject {
 
     /**
      * Gets the abandoned conversation's conversation context.
+     *
      * @return The abandoned conversation's conversation context.
      */
     public ConversationContext getContext() {
@@ -39,6 +41,7 @@ public class ConversationAbandonedEvent extends EventObject {
     /**
      * Indicates how the conversation was abandoned - naturally as part of the prompt chain or prematurely via a
      * {@link ConversationCanceller}.
+     *
      * @return True if the conversation is abandoned gracefully by a {@link Prompt} returning null
      * or the next prompt. False of the conversations is abandoned prematurely by a ConversationCanceller.
      */

paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java

@@ -7,6 +7,7 @@ import java.util.EventListener;
 public interface ConversationAbandonedListener extends EventListener {
     /**
      * Called whenever a {@link Conversation} is abandoned.
+     *
      * @param abandonedEvent Contains details about the abandoned conversation.
      */
     public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent);

paper-api/src/main/java/org/bukkit/conversations/ConversationCanceller.java

@@ -8,12 +8,14 @@ public interface ConversationCanceller extends Cloneable {
 
     /**
      * Sets the conversation this ConversationCanceller can optionally cancel.
+     *
      * @param conversation A conversation.
      */
     public void setConversation(Conversation conversation);
 
     /**
-     * Cancels a conversation based on user input/
+     * Cancels a conversation based on user input.
+     *
      * @param context Context information about the conversation.
      * @param input The input text from the user.
      * @return True to cancel the conversation, False otherwise.
@@ -22,7 +24,9 @@ public interface ConversationCanceller extends Cloneable {
 
     /**
      * Allows the {@link ConversationFactory} to duplicate this ConversationCanceller when creating a new {@link Conversation}.
+     * <p>
      * Implementing this method should reset any internal object state.
+     *
      * @return A clone.
      */
     public ConversationCanceller clone();

paper-api/src/main/java/org/bukkit/conversations/ConversationContext.java

@@ -27,6 +27,7 @@ public class ConversationContext {
 
     /**
      * Gets the plugin that owns this conversation.
+     *
      * @return The owning plugin.
      */
     public Plugin getPlugin() {
@@ -35,6 +36,7 @@ public class ConversationContext {
 
     /**
      * Gets the subject of the conversation.
+     *
      * @return The subject of the conversation.
      */
     public Conversable getForWhom() {
@@ -44,6 +46,7 @@ public class ConversationContext {
     /**
      * Gets session data shared between all {@link Prompt} invocations. Use this as a way
      * to pass data through each Prompt as the conversation develops.
+     *
      * @param key The session data key.
      * @return The requested session data.
      */
@@ -54,6 +57,7 @@ public class ConversationContext {
     /**
      * Sets session data shared between all {@link Prompt} invocations. Use this as a way to pass
      * data through each prompt as the conversation develops.
+     *
      * @param key The session data key.
      * @param value The session data value.
      */

paper-api/src/main/java/org/bukkit/conversations/ConversationFactory.java

@@ -12,7 +12,7 @@ import java.util.Map;
  * A ConversationFactory is responsible for creating a {@link Conversation} from a predefined template. A ConversationFactory
  * is typically created when a plugin is instantiated and builds a Conversation each time a user initiates a conversation
  * with the plugin. Each Conversation maintains its own state and calls back as needed into the plugin.
- *
+ * <p>
  * The ConversationFactory implements a fluid API, allowing parameters to be set as an extension to the constructor.
  */
 public class ConversationFactory {
@@ -29,6 +29,7 @@ public class ConversationFactory {
 
     /**
      * Constructs a ConversationFactory.
+     *
      * @param plugin The plugin that owns the factory.
      */
     public ConversationFactory(Plugin plugin)
@@ -47,8 +48,9 @@ public class ConversationFactory {
     /**
      * Sets the modality of all {@link Conversation}s created by this factory. If a conversation is modal, all messages
      * directed to the player are suppressed for the duration of the conversation.
-     *
+     * <p>
      * The default is True.
+     *
      * @param modal The modality of all conversations to be created.
      * @return This object.
      */
@@ -61,6 +63,7 @@ public class ConversationFactory {
     /**
      * Sets the local echo status for all {@link Conversation}s created by this factory. If local echo is enabled,
      * any text submitted to a conversation gets echoed back into the submitter's chat window.
+     *
      * @param localEchoEnabled The status of local echo.
      * @return This object.
      */
@@ -71,8 +74,9 @@ public class ConversationFactory {
 
     /**
      * Sets the {@link ConversationPrefix} that prepends all output from all generated conversations.
-     *
+     * <p>
      * The default is a {@link NullConversationPrefix};
+     *
      * @param prefix The ConversationPrefix to use.
      * @return This object.
      */
@@ -83,8 +87,9 @@ public class ConversationFactory {
 
     /**
      * Sets the number of inactive seconds to wait before automatically abandoning all generated conversations.
-     *
+     * <p>
      * The default is 600 seconds (5 minutes).
+     *
      * @param timeoutSeconds The number of seconds to wait.
      * @return This object.
      */
@@ -94,8 +99,9 @@ public class ConversationFactory {
 
     /**
      * Sets the first prompt to use in all generated conversations.
-     *
+     * <p>
      * The default is Prompt.END_OF_CONVERSATION.
+     *
      * @param firstPrompt The first prompt.
      * @return This object.
      */
@@ -106,6 +112,7 @@ public class ConversationFactory {
 
     /**
      * Sets any initial data with which to populate the conversation context sessionData map.
+     *
      * @param initialSessionData The conversation context's initial sessionData.
      * @return This object.
      */
@@ -116,6 +123,7 @@ public class ConversationFactory {
 
     /**
      * Sets the player input that, when received, will immediately terminate the conversation.
+     *
      * @param escapeSequence Input to terminate the conversation.
      * @return This object.
      */
@@ -126,6 +134,7 @@ public class ConversationFactory {
 
     /**
      * Adds a {@link ConversationCanceller to constructed conversations.}
+     *
      * @param canceller The {@link ConversationCanceller to add.}
      * @return This object.
      */
@@ -136,6 +145,7 @@ public class ConversationFactory {
 
     /**
      * Prevents this factory from creating a conversation for non-player {@link Conversable} objects.
+     *
      * @param playerOnlyMessage The message to return to a non-play in lieu of starting a conversation.
      * @return This object.
      */
@@ -146,6 +156,7 @@ public class ConversationFactory {
 
     /**
      * Adds a {@link ConversationAbandonedListener} to all conversations constructed by this factory.
+     *
      * @param listener The listener to add.
      * @return This object.
      */
@@ -156,6 +167,7 @@ public class ConversationFactory {
 
     /**
      * Constructs a {@link Conversation} in accordance with the defaults set for this factory.
+     *
      * @param forWhom The entity for whom the new conversation is mediating.
      * @return A new conversation.
      */

paper-api/src/main/java/org/bukkit/conversations/ConversationPrefix.java

@@ -10,6 +10,7 @@ public interface ConversationPrefix {
 
     /**
      * Gets the prefix to use before each message to the player.
+     *
      * @param context Context information about the conversation.
      * @return The prefix text.
      */

paper-api/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java

@@ -8,6 +8,7 @@ public class ExactMatchConversationCanceller implements ConversationCanceller {
 
     /**
      * Builds an ExactMatchConversationCanceller.
+     *
      * @param escapeSequence The string that, if entered by the user, will cancel the conversation.
      */
     public ExactMatchConversationCanceller(String escapeSequence) {

paper-api/src/main/java/org/bukkit/conversations/FixedSetPrompt.java

@@ -15,6 +15,7 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
     /**
      * Creates a FixedSetPrompt from a set of strings.
      * foo = new FixedSetPrompt("bar", "cheese", "panda");
+     *
      * @param fixedSet A fixed set of strings, one of which the user must type.
      */
     public FixedSetPrompt(String... fixedSet) {
@@ -31,7 +32,7 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
 
     /**
      * Utility function to create a formatted string containing all the options declared in the constructor.
-     * 
+     *
      * @return the options formatted like "[bar, cheese, panda]" if bar, cheese, and panda were the options used
      */
     protected String formatFixedSet() {

paper-api/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java

@@ -14,6 +14,7 @@ public class InactivityConversationCanceller implements ConversationCanceller {
 
     /**
      * Creates an InactivityConversationCanceller.
+     *
      * @param plugin The owning plugin.
      * @param timeoutSeconds The number of seconds of inactivity to wait.
      */
@@ -67,6 +68,7 @@ public class InactivityConversationCanceller implements ConversationCanceller {
     /**
      * Subclasses of InactivityConversationCanceller can override this method to take additional actions when the
      * inactivity timer abandons the conversation.
+     *
      * @param conversation The conversation being abandoned.
      */
     protected void cancelling(Conversation conversation) {

paper-api/src/main/java/org/bukkit/conversations/MessagePrompt.java

@@ -11,6 +11,7 @@ public abstract class MessagePrompt implements Prompt{
 
     /**
      * Message prompts never wait for user input before continuing.
+     *
      * @param context Context information about the conversation.
      * @return Always false.
      */
@@ -20,6 +21,7 @@ public abstract class MessagePrompt implements Prompt{
 
     /**
      * Accepts and ignores any user input, returning the next prompt in the prompt graph instead.
+     *
      * @param context Context information about the conversation.
      * @param input Ignored.
      * @return The next prompt in the prompt graph.
@@ -30,6 +32,7 @@ public abstract class MessagePrompt implements Prompt{
 
     /**
      * Override this method to return the next prompt in the prompt graph.
+     *
      * @param context Context information about the conversation.
      * @return The next prompt in the prompt graph.
      */

paper-api/src/main/java/org/bukkit/conversations/NullConversationPrefix.java

@@ -10,6 +10,7 @@ public class NullConversationPrefix implements ConversationPrefix{
 
     /**
      * Prepends each conversation message with an empty string.
+     *
      * @param context Context information about the conversation.
      * @return An empty string.
      */

paper-api/src/main/java/org/bukkit/conversations/NumericPrompt.java

@@ -18,6 +18,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
     /**
      * Override this method to do further validation on the numeric player input after the input has been determined
      * to actually be a number.
+     *
      * @param context Context information about the conversation.
      * @param input The number the player provided.
      * @return The validity of the player's input.
@@ -38,6 +39,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
 
     /**
      * Override this method to perform some action with the user's integer response.
+     *
      * @param context Context information about the conversation.
      * @param input The user's response as a {@link Number}.
      * @return The next {@link Prompt} in the prompt graph.
@@ -55,6 +57,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
 
     /**
      * Optionally override this method to display an additional message if the user enters an invalid number.
+     *
      * @param context Context information about the conversation.
      * @param invalidInput The invalid input provided by the user.
      * @return A message explaining how to correct the input.
@@ -65,6 +68,7 @@ public abstract class NumericPrompt extends ValidatingPrompt{
 
     /**
      * Optionally override this method to display an additional message if the user enters an invalid numeric input.
+     *
      * @param context Context information about the conversation.
      * @param invalidInput The invalid input provided by the user.
      * @return A message explaining how to correct the input.

paper-api/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java

@@ -27,6 +27,7 @@ public abstract class PlayerNamePrompt extends ValidatingPrompt{
 
     /**
      * Override this method to perform some action with the user's player name response.
+     *
      * @param context Context information about the conversation.
      * @param input The user's player name response.
      * @return The next {@link Prompt} in the prompt graph.

paper-api/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java

@@ -30,6 +30,7 @@ public class PluginNameConversationPrefix implements ConversationPrefix {
 
     /**
      * Prepends each conversation message with the plugin name.
+     *
      * @param context Context information about the conversation.
      * @return An empty string.
      */

paper-api/src/main/java/org/bukkit/conversations/Prompt.java

@@ -14,6 +14,7 @@ public interface Prompt extends Cloneable {
 
     /**
      * Gets the text to display to the user when this prompt is first presented.
+     *
      * @param context Context information about the conversation.
      * @return The text to display.
      */
@@ -21,6 +22,7 @@ public interface Prompt extends Cloneable {
 
     /**
      * Checks to see if this prompt implementation should wait for user input or immediately display the next prompt.
+     *
      * @param context Context information about the conversation.
      * @return If true, the {@link Conversation} will wait for input before continuing.
      */
@@ -28,6 +30,7 @@ public interface Prompt extends Cloneable {
 
     /**
      * Accepts and processes input from the user. Using the input, the next Prompt in the prompt graph is returned.
+     *
      * @param context Context information about the conversation.
      * @param input The input text from the user.
      * @return The next Prompt in the prompt graph.

paper-api/src/main/java/org/bukkit/conversations/StringPrompt.java

@@ -7,6 +7,7 @@ public abstract class StringPrompt implements Prompt{
 
     /**
      * Ensures that the prompt waits for the user to provide input.
+     *
      * @param context Context information about the conversation.
      * @return True.
      */

paper-api/src/main/java/org/bukkit/conversations/ValidatingPrompt.java

@@ -14,6 +14,7 @@ public abstract class ValidatingPrompt implements Prompt {
     /**
      * Accepts and processes input from the user and validates it. If validation fails, this prompt is returned for
      * re-execution, otherwise the next Prompt in the prompt graph is returned.
+     *
      * @param context Context information about the conversation.
      * @param input The input text from the user.
      * @return This prompt or the next Prompt in the prompt graph.
@@ -33,6 +34,7 @@ public abstract class ValidatingPrompt implements Prompt {
 
     /**
      * Ensures that the prompt waits for the user to provide input.
+     *
      * @param context Context information about the conversation.
      * @return True.
      */
@@ -42,6 +44,7 @@ public abstract class ValidatingPrompt implements Prompt {
 
     /**
      * Override this method to check the validity of the player's input.
+     *
      * @param context Context information about the conversation.
      * @param input The player's raw console input.
      * @return True or false depending on the validity of the input.
@@ -51,6 +54,7 @@ public abstract class ValidatingPrompt implements Prompt {
     /**
      * Override this method to accept and processes the validated input from the user. Using the input, the next Prompt
      * in the prompt graph should be returned.
+     *
      * @param context Context information about the conversation.
      * @param input The validated input text from the user.
      * @return The next Prompt in the prompt graph.
@@ -59,6 +63,7 @@ public abstract class ValidatingPrompt implements Prompt {
 
     /**
      * Optionally override this method to display an additional message if the user enters an invalid input.
+     *
      * @param context Context information about the conversation.
      * @param invalidInput The invalid input provided by the user.
      * @return A message explaining how to correct the input.