Pulling all pending Bukkit-JavaDoc changes

src/main/java/org/bukkit/ChunkSnapshot.java

@@ -114,6 +114,7 @@ public interface ChunkSnapshot {
 
     /**
      * Test if section is empty
+     *
      * @param sy - section Y coordinate (block Y / 16)
      * @return true if empty, false if not
      */

src/main/java/org/bukkit/FireworkEffect.java

@@ -54,6 +54,7 @@ public static Builder builder() {
 
     /**
      * This is a builder for FireworkEffects.
+     *
      * @see FireworkEffect#builder()
      */
     public static final class Builder {

src/main/java/org/bukkit/Instrument.java

@@ -43,6 +43,7 @@ public byte getType() {
 
     /**
      * Get an instrument by its type ID.
+     *
      * @param type The type ID
      * @return The instrument
      */

src/main/java/org/bukkit/Server.java

@@ -608,6 +608,7 @@ public interface Server extends PluginMessageRecipient {
      * Creates an empty inventory of the specified type. If the type is {@link InventoryType#CHEST},
      * the new inventory has a size of 27; otherwise the new inventory has the normal size for
      * its type.
+     *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param type The type of inventory to create.
      * @return The new inventory.
@@ -616,6 +617,7 @@ public interface Server extends PluginMessageRecipient {
 
     /**
      * Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size.
+     *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param size The size of inventory to create; must be a multiple of 9.
      * @return The new inventory.
@@ -625,6 +627,7 @@ public interface Server extends PluginMessageRecipient {
 
     /**
      * Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size and title.
+     *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param size The size of inventory to create; must be a multiple of 9.
      * @param title The title of the inventory, to be displayed when it is viewed.
@@ -635,24 +638,28 @@ public interface Server extends PluginMessageRecipient {
 
     /**
      * Gets user-specified limit for number of monsters that can spawn in a chunk
+     *
      * @return The monster spawn limit
      */
     int getMonsterSpawnLimit();
 
     /**
      * Gets user-specified limit for number of animals that can spawn in a chunk
+     *
      * @return The animal spawn limit
      */
     int getAnimalSpawnLimit();
 
     /**
      * Gets user-specified limit for number of water animals that can spawn in a chunk
+     *
      * @return The water animal spawn limit
      */
     int getWaterAnimalSpawnLimit();
 
     /**
      * Gets user-specified limit for number of ambient mobs that can spawn in a chunk
+     *
      * @return The ambient spawn limit
      */
     int getAmbientSpawnLimit();

src/main/java/org/bukkit/Warning.java

@@ -50,6 +50,7 @@ public enum WarningState {
 
         /**
          * This method checks the provided warning should be printed for this state
+         *
          * @param warning The warning annotation added to a deprecated item
          * @return ON is always True<br>
          *  OFF is always false<br>
@@ -64,6 +65,7 @@ public boolean printFor(Warning warning) {
 
         /**
          * This method returns the corresponding warning state for the given string value.
+         *
          * @param value The string value to check
          * @return {@link #DEFAULT} if not found, or the respective WarningState
          */
@@ -81,12 +83,14 @@ public static WarningState value(final String value) {
 
     /**
      * This sets if the deprecation warnings when registering events gets printed when the setting is in the default state.
+     *
      * @return false normally, or true to encourage warning printout
      */
     boolean value() default false;
 
     /**
      * This can provide detailed information on why the event is deprecated.
+     *
      * @return The reason an event is deprecated
      */
     String reason() default "";

src/main/java/org/bukkit/World.java

@@ -972,6 +972,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets the limit for number of animals that can spawn in a chunk in this world
+     *
      * @return The animal spawn limit
      */
     int getAnimalSpawnLimit();
@@ -986,6 +987,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets the limit for number of water animals that can spawn in a chunk in this world
+     *
      * @return The water animal spawn limit
      */
     int getWaterAnimalSpawnLimit();
@@ -1000,6 +1002,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets the limit for number of ambient mobs that can spawn in a chunk in this world
+     *
      * @return The ambient spawn limit
      */
     int getAmbientSpawnLimit();
@@ -1098,6 +1101,7 @@ public int getId() {
 
         /**
          * Get an environment by ID
+         *
          * @param id The ID of the environment
          * @return The environment
          */

src/main/java/org/bukkit/conversations/BooleanPrompt.java

@@ -25,6 +25,7 @@ protected Prompt acceptValidatedInput(ConversationContext context, String input)
 
     /**
      * 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.

src/main/java/org/bukkit/conversations/Conversable.java

@@ -9,32 +9,37 @@ 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();
 
     /**
      * 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
      */
     public boolean beginConversation(Conversation conversation);
 
     /**
      * 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
      */

src/main/java/org/bukkit/conversations/Conversation.java

@@ -11,18 +11,18 @@
  * 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 Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt) {
 
     /**
      * 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 Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt, Map<
 
     /**
      * Gets the entity for whom this conversation is mediating.
+     *
      * @return The entity.
      */
     public Conversable getForWhom() {
@@ -76,6 +79,7 @@ public Conversable getForWhom() {
     /**
      * 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 boolean isModal() {
     /**
      * 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 @@ void setModal(boolean modal) {
     /**
      * 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 boolean isLocalEchoEnabled() {
     /**
      * 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 void setLocalEchoEnabled(boolean localEchoEnabled) {
 
     /**
      * Gets the {@link ConversationPrefix} that prepends all output from this conversation.
+     *
      * @return The ConversationPrefix in use.
      */
     public ConversationPrefix getPrefix() {
@@ -119,6 +127,7 @@ public ConversationPrefix getPrefix() {
 
     /**
      * 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 @@ void setPrefix(ConversationPrefix prefix) {
 
     /**
      * Adds a {@link ConversationCanceller} to the cancellers collection.
+     *
      * @param canceller The {@link ConversationCanceller} to add.
      */
     void addConversationCanceller(ConversationCanceller canceller) {
@@ -136,6 +146,7 @@ void addConversationCanceller(ConversationCanceller canceller) {
 
     /**
      * Gets the list of {@link ConversationCanceller}s
+     *
      * @return The list.
      */
     public List<ConversationCanceller> getCancellers() {
@@ -144,6 +155,7 @@ public List<ConversationCanceller> getCancellers() {
 
     /**
      * Returns the Conversation's {@link ConversationContext}.
+     *
      * @return The ConversationContext.
      */
     public ConversationContext getContext() {

src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java

@@ -22,6 +22,7 @@ public ConversationAbandonedEvent(Conversation conversation, ConversationCancell
 
     /**
      * 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 ConversationCanceller getCanceller() {
 
     /**
      * Gets the abandoned conversation's conversation context.
+     *
      * @return The abandoned conversation's conversation context.
      */
     public ConversationContext getContext() {
@@ -39,6 +41,7 @@ public ConversationContext getContext() {
     /**
      * 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.
      */

src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java

@@ -7,6 +7,7 @@
 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);

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();

src/main/java/org/bukkit/conversations/ConversationContext.java

@@ -27,6 +27,7 @@ public ConversationContext(Plugin plugin, Conversable forWhom, Map<Object, Objec
 
     /**
      * Gets the plugin that owns this conversation.
+     *
      * @return The owning plugin.
      */
     public Plugin getPlugin() {
@@ -35,6 +36,7 @@ public Plugin getPlugin() {
 
     /**
      * Gets the subject of the conversation.
+     *
      * @return The subject of the conversation.
      */
     public Conversable getForWhom() {
@@ -44,6 +46,7 @@ public Conversable getForWhom() {
     /**
      * 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 Object getSessionData(Object key) {
     /**
      * 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.
      */