Pulling all pending Bukkit-JavaDoc changes

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

By: Wesley Wolfe <weswolf@aol.com>

paper-api/src/main/java/org/bukkit/metadata/FixedMetadataValue.java

@@ -5,21 +5,26 @@ import org.bukkit.plugin.Plugin;
 import java.util.concurrent.Callable;
 
 /**
- * A FixedMetadataValue is a special case metadata item that contains the same value forever after initialization.
- * Invalidating a FixedMetadataValue has no effect.
+ * A FixedMetadataValue is a special case metadata item that contains the same
+ * value forever after initialization. Invalidating a FixedMetadataValue has
+ * no effect.
  * <p>
- * This class extends LazyMetadataValue for historical reasons, even though it overrides all the implementation
- * methods. it is possible that in the future that the inheritance hierarchy may change.
+ * This class extends LazyMetadataValue for historical reasons, even though it
+ * overrides all the implementation methods. it is possible that in the future
+ * that the inheritance hierarchy may change.
  */
 public class FixedMetadataValue extends LazyMetadataValue {
-    /** Store the internal value that is represented by this fixed value. */
+
+    /**
+     * Store the internal value that is represented by this fixed value.
+     */
     private final Object internalValue;
 
     /**
      * Initializes a FixedMetadataValue with an Object
      *
-     * @param owningPlugin the {@link Plugin} that created this metadata value.
-     * @param value the value assigned to this metadata value.
+     * @param owningPlugin the {@link Plugin} that created this metadata value
+     * @param value the value assigned to this metadata value
      */
     public FixedMetadataValue(Plugin owningPlugin, final Object value) {
         super(owningPlugin);

paper-api/src/main/java/org/bukkit/metadata/LazyMetadataValue.java

@@ -7,10 +7,14 @@ import org.apache.commons.lang.Validate;
 import org.bukkit.plugin.Plugin;
 
 /**
- * The LazyMetadataValue class implements a type of metadata that is not computed until another plugin asks for it.
- * By making metadata values lazy, no computation is done by the providing plugin until absolutely necessary (if ever).
- * Additionally, LazyMetadataValue objects cache their values internally unless overridden by a {@link CacheStrategy}
- * or invalidated at the individual or plugin level. Once invalidated, the LazyMetadataValue will recompute its value
+ * The LazyMetadataValue class implements a type of metadata that is not
+ * computed until another plugin asks for it.
+ * <p>
+ * By making metadata values lazy, no computation is done by the providing
+ * plugin until absolutely necessary (if ever). Additionally,
+ * LazyMetadataValue objects cache their values internally unless overridden
+ * by a {@link CacheStrategy} or invalidated at the individual or plugin
+ * level. Once invalidated, the LazyMetadataValue will recompute its value
  * when asked.
  */
 public class LazyMetadataValue extends MetadataValueAdapter implements MetadataValue {
@@ -20,9 +24,11 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV
     private static final Object ACTUALLY_NULL = new Object();
 
     /**
-     * Initialized a LazyMetadataValue object with the default CACHE_AFTER_FIRST_EVAL cache strategy.
+     * Initialized a LazyMetadataValue object with the default
+     * CACHE_AFTER_FIRST_EVAL cache strategy.
      *
-     * @param owningPlugin the {@link Plugin} that created this metadata value.
+     * @param owningPlugin the {@link Plugin} that created this metadata
+     *     value.
      * @param lazyValue the lazy value assigned to this metadata value.
      */
     public LazyMetadataValue(Plugin owningPlugin, Callable<Object> lazyValue) {
@@ -32,8 +38,10 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV
     /**
      * Initializes a LazyMetadataValue object with a specific cache strategy.
      *
-     * @param owningPlugin the {@link Plugin} that created this metadata value.
-     * @param cacheStrategy determines the rules for caching this metadata value.
+     * @param owningPlugin the {@link Plugin} that created this metadata
+     *     value.
+     * @param cacheStrategy determines the rules for caching this metadata
+     *     value.
      * @param lazyValue the lazy value assigned to this metadata value.
      */
     public LazyMetadataValue(Plugin owningPlugin, CacheStrategy cacheStrategy, Callable<Object> lazyValue) {
@@ -45,7 +53,10 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV
         this.cacheStrategy = cacheStrategy;
     }
 
-    /** Protected special constructor used by FixedMetadataValue to bypass standard setup. */
+    /**
+     * Protected special constructor used by FixedMetadataValue to bypass
+     * standard setup.
+     */
     protected LazyMetadataValue(Plugin owningPlugin) {
         super(owningPlugin);
     }
@@ -62,7 +73,8 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV
     /**
      * Lazily evaluates the value of this metadata item.
      *
-     * @throws MetadataEvaluationException if computing the metadata value fails.
+     * @throws MetadataEvaluationException if computing the metadata value
+     *     fails.
      */
     private synchronized void eval() throws MetadataEvaluationException {
         if (cacheStrategy == CacheStrategy.NEVER_CACHE || internalValue.get() == null) {
@@ -89,7 +101,8 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV
      */
     public enum CacheStrategy {
         /**
-         * Once the metadata value has been evaluated, do not re-evaluate the value until it is manually invalidated.
+         * Once the metadata value has been evaluated, do not re-evaluate the
+         * value until it is manually invalidated.
          */
         CACHE_AFTER_FIRST_EVAL,
 
@@ -99,7 +112,8 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV
         NEVER_CACHE,
 
         /**
-         * Once the metadata value has been evaluated, do not re-evaluate the value in spite of manual invalidation.
+         * Once the metadata value has been evaluated, do not re-evaluate the
+         * value in spite of manual invalidation.
          */
         CACHE_ETERNALLY
     }

paper-api/src/main/java/org/bukkit/metadata/MetadataConversionException.java

@@ -1,10 +1,10 @@
 package org.bukkit.metadata;
 
 /**
- * A MetadataConversionException is thrown any time a {@link LazyMetadataValue} attempts to convert a metadata value
- * to an inappropriate data type.
+ * A MetadataConversionException is thrown any time a {@link
+ * LazyMetadataValue} attempts to convert a metadata value to an inappropriate
+ * data type.
  */
-
 @SuppressWarnings("serial")
 public class MetadataConversionException extends RuntimeException {
     MetadataConversionException(String message) {

paper-api/src/main/java/org/bukkit/metadata/MetadataEvaluationException.java

@@ -1,10 +1,10 @@
 package org.bukkit.metadata;
 
 /**
- * A MetadataEvaluationException is thrown any time a {@link LazyMetadataValue} fails to evaluate its value due to
- * an exception. The originating exception will be included as this exception's cause.
+ * A MetadataEvaluationException is thrown any time a {@link
+ * LazyMetadataValue} fails to evaluate its value due to an exception. The
+ * originating exception will be included as this exception's cause.
  */
-
 @SuppressWarnings("serial")
 public class MetadataEvaluationException extends RuntimeException {
     MetadataEvaluationException(Throwable cause) {

paper-api/src/main/java/org/bukkit/metadata/MetadataStore.java

@@ -11,24 +11,27 @@ public interface MetadataStore<T> {
      * @param subject The object receiving the metadata.
      * @param metadataKey A unique key to identify this metadata.
      * @param newMetadataValue The metadata value to apply.
-     * @throws IllegalArgumentException If value is null, or the owning plugin is null
+     * @throws IllegalArgumentException If value is null, or the owning plugin
+     *     is null
      */
     public void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue);
 
     /**
-     * Returns all metadata values attached to an object. If multiple plugins have attached metadata, each will value
-     * will be included.
+     * Returns all metadata values attached to an object. If multiple plugins
+     * have attached metadata, each will value will be included.
      *
      * @param subject the object being interrogated.
      * @param metadataKey the unique metadata key being sought.
-     * @return A list of values, one for each plugin that has set the requested value.
+     * @return A list of values, one for each plugin that has set the
+     *     requested value.
      */
     public List<MetadataValue> getMetadata(T subject, String metadataKey);
 
     /**
      * Tests to see if a metadata attribute has been set on an object.
      *
-     * @param subject the object upon which the has-metadata test is performed.
+     * @param subject the object upon which the has-metadata test is
+     *     performed.
      * @param metadataKey the unique metadata key being queried.
      * @return the existence of the metadataKey within subject.
      */
@@ -38,15 +41,17 @@ public interface MetadataStore<T> {
      * Removes a metadata item owned by a plugin from a subject.
      *
      * @param subject the object to remove the metadata from.
-     * @param metadataKey the unique metadata key identifying the metadata to remove.
+     * @param metadataKey the unique metadata key identifying the metadata to
+     *     remove.
      * @param owningPlugin the plugin attempting to remove a metadata item.
      * @throws IllegalArgumentException If plugin is null
      */
     public void removeMetadata(T subject, String metadataKey, Plugin owningPlugin);
 
     /**
-     * Invalidates all metadata in the metadata store that originates from the given plugin. Doing this will force
-     * each invalidated metadata item to be recalculated the next time it is accessed.
+     * Invalidates all metadata in the metadata store that originates from the
+     * given plugin. Doing this will force each invalidated metadata item to
+     * be recalculated the next time it is accessed.
      *
      * @param owningPlugin the plugin requesting the invalidation.
      * @throws IllegalArgumentException If plugin is null

paper-api/src/main/java/org/bukkit/metadata/MetadataStoreBase.java

@@ -9,20 +9,26 @@ public abstract class MetadataStoreBase<T> {
     private Map<String, Map<Plugin, MetadataValue>> metadataMap = new HashMap<String, Map<Plugin, MetadataValue>>();
 
     /**
-     * Adds a metadata value to an object. Each metadata value is owned by a specific{@link Plugin}.
-     * If a plugin has already added a metadata value to an object, that value
-     * will be replaced with the value of {@code newMetadataValue}. Multiple plugins can set independent values for
-     * the same {@code metadataKey} without conflict.
-     * <p/>
-     * Implementation note: I considered using a {@link java.util.concurrent.locks.ReadWriteLock} for controlling
-     * access to {@code metadataMap}, but decided that the added overhead wasn't worth the finer grained access control.
-     * Bukkit is almost entirely single threaded so locking overhead shouldn't pose a problem.
+     * Adds a metadata value to an object. Each metadata value is owned by a
+     * specific {@link Plugin}. If a plugin has already added a metadata value
+     * to an object, that value will be replaced with the value of {@code
+     * newMetadataValue}. Multiple plugins can set independent values for the
+     * same {@code metadataKey} without conflict.
+     * <p>
+     * Implementation note: I considered using a {@link
+     * java.util.concurrent.locks.ReadWriteLock} for controlling access to
+     * {@code metadataMap}, but decided that the added overhead wasn't worth
+     * the finer grained access control.
+     * <p>
+     * Bukkit is almost entirely single threaded so locking overhead shouldn't
+     * pose a problem.
      *
-     * @param subject          The object receiving the metadata.
-     * @param metadataKey      A unique key to identify this metadata.
+     * @param subject The object receiving the metadata.
+     * @param metadataKey A unique key to identify this metadata.
      * @param newMetadataValue The metadata value to apply.
      * @see MetadataStore#setMetadata(Object, String, MetadataValue)
-     * @throws IllegalArgumentException If value is null, or the owning plugin is null
+     * @throws IllegalArgumentException If value is null, or the owning plugin
+     *     is null
      */
     public synchronized void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue) {
         Validate.notNull(newMetadataValue, "Value cannot be null");
@@ -38,12 +44,13 @@ public abstract class MetadataStoreBase<T> {
     }
 
     /**
-     * Returns all metadata values attached to an object. If multiple plugins have attached metadata, each will value
-     * will be included.
+     * Returns all metadata values attached to an object. If multiple
+     * have attached metadata, each will value will be included.
      *
-     * @param subject     the object being interrogated.
+     * @param subject the object being interrogated.
      * @param metadataKey the unique metadata key being sought.
-     * @return A list of values, one for each plugin that has set the requested value.
+     * @return A list of values, one for each plugin that has set the
+     *     requested value.
      * @see MetadataStore#getMetadata(Object, String)
      */
     public synchronized List<MetadataValue> getMetadata(T subject, String metadataKey) {
@@ -59,7 +66,8 @@ public abstract class MetadataStoreBase<T> {
     /**
      * Tests to see if a metadata attribute has been set on an object.
      *
-     * @param subject     the object upon which the has-metadata test is performed.
+     * @param subject the object upon which the has-metadata test is
+     *     performed.
      * @param metadataKey the unique metadata key being queried.
      * @return the existence of the metadataKey within subject.
      */
@@ -71,10 +79,12 @@ public abstract class MetadataStoreBase<T> {
     /**
      * Removes a metadata item owned by a plugin from a subject.
      *
-     * @param subject      the object to remove the metadata from.
-     * @param metadataKey  the unique metadata key identifying the metadata to remove.
+     * @param subject the object to remove the metadata from.
+     * @param metadataKey the unique metadata key identifying the metadata to
+     *     remove.
      * @param owningPlugin the plugin attempting to remove a metadata item.
-     * @see MetadataStore#removeMetadata(Object, String, org.bukkit.plugin.Plugin)
+     * @see MetadataStore#removeMetadata(Object, String,
+     *     org.bukkit.plugin.Plugin)
      * @throws IllegalArgumentException If plugin is null
      */
     public synchronized void removeMetadata(T subject, String metadataKey, Plugin owningPlugin) {
@@ -92,8 +102,9 @@ public abstract class MetadataStoreBase<T> {
     }
 
     /**
-     * Invalidates all metadata in the metadata store that originates from the given plugin. Doing this will force
-     * each invalidated metadata item to be recalculated the next time it is accessed.
+     * Invalidates all metadata in the metadata store that originates from the
+     * given plugin. Doing this will force each invalidated metadata item to
+     * be recalculated the next time it is accessed.
      *
      * @param owningPlugin the plugin requesting the invalidation.
      * @see MetadataStore#invalidateAll(org.bukkit.plugin.Plugin)
@@ -109,12 +120,15 @@ public abstract class MetadataStoreBase<T> {
     }
 
     /**
-     * Creates a unique name for the object receiving metadata by combining unique data from the subject with a metadataKey.
-     * The name created must be globally unique for the given object and any two equivalent objects must generate the
-     * same unique name. For example, two Player objects must generate the same string if they represent the same player,
-     * even if the objects would fail a reference equality test.
+     * Creates a unique name for the object receiving metadata by combining
+     * unique data from the subject with a metadataKey.
+     * <p>
+     * The name created must be globally unique for the given object and any
+     * two equivalent objects must generate the same unique name. For example,
+     * two Player objects must generate the same string if they represent the
+     * same player, even if the objects would fail a reference equality test.
      *
-     * @param subject     The object for which this key is being generated.
+     * @param subject The object for which this key is being generated.
      * @param metadataKey The name identifying the metadata value.
      * @return a unique metadata key for the given subject.
      */

paper-api/src/main/java/org/bukkit/metadata/MetadataValue.java

@@ -70,12 +70,14 @@ public interface MetadataValue {
     /**
      * Returns the {@link Plugin} that created this metadata item.
      *
-     * @return the plugin that owns this metadata value. This should never be null.
+     * @return the plugin that owns this metadata value. This should never be
+     *     null.
      */
     public Plugin getOwningPlugin();
 
     /**
-     * Invalidates this metadata item, forcing it to recompute when next accessed.
+     * Invalidates this metadata item, forcing it to recompute when next
+     * accessed.
      */
     public void invalidate();
 }

paper-api/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java

@@ -9,9 +9,9 @@ import org.bukkit.util.NumberConversions;
 /**
  * Optional base class for facilitating MetadataValue implementations.
  * <p>
- * This provides all the conversion functions for MetadataValue
- * so that writing an implementation of MetadataValue is as simple
- * as implementing value() and invalidate().
+ * This provides all the conversion functions for MetadataValue so that
+ * writing an implementation of MetadataValue is as simple as implementing
+ * value() and invalidate().
  */
 public abstract class MetadataValueAdapter implements MetadataValue {
     protected final WeakReference<Plugin> owningPlugin;

paper-api/src/main/java/org/bukkit/metadata/Metadatable.java

@@ -5,7 +5,8 @@ import org.bukkit.plugin.Plugin;
 import java.util.List;
 
 /**
- * This interface is implemented by all objects that can provide metadata about themselves.
+ * This interface is implemented by all objects that can provide metadata
+ * about themselves.
  */
 public interface Metadatable {
     /**
@@ -13,20 +14,24 @@ public interface Metadatable {
      *
      * @param metadataKey A unique key to identify this metadata.
      * @param newMetadataValue The metadata value to apply.
-     * @throws IllegalArgumentException If value is null, or the owning plugin is null
+     * @throws IllegalArgumentException If value is null, or the owning plugin
+     *     is null
      */
     public void setMetadata(String metadataKey, MetadataValue newMetadataValue);
 
     /**
-     * Returns a list of previously set metadata values from the implementing object's metadata store.
+     * Returns a list of previously set metadata values from the implementing
+     * object's metadata store.
      *
      * @param metadataKey the unique metadata key being sought.
-     * @return A list of values, one for each plugin that has set the requested value.
+     * @return A list of values, one for each plugin that has set the
+     *     requested value.
      */
     public List<MetadataValue> getMetadata(String metadataKey);
 
     /**
-     * Tests to see whether the implementing object contains the given metadata value in its metadata store.
+     * Tests to see whether the implementing object contains the given
+     * metadata value in its metadata store.
      *
      * @param metadataKey the unique metadata key being queried.
      * @return the existence of the metadataKey within subject.
@@ -34,10 +39,13 @@ public interface Metadatable {
     public boolean hasMetadata(String metadataKey);
 
     /**
-     * Removes the given metadata value from the implementing object's metadata store.
+     * Removes the given metadata value from the implementing object's
+     * metadata store.
      *
-     * @param metadataKey the unique metadata key identifying the metadata to remove.
-     * @param owningPlugin This plugin's metadata value will be removed. All other values will be left untouched.
+     * @param metadataKey the unique metadata key identifying the metadata to
+     *     remove.
+     * @param owningPlugin This plugin's metadata value will be removed. All
+     *     other values will be left untouched.
      * @throws IllegalArgumentException If plugin is null
      */
     public void removeMetadata(String metadataKey, Plugin owningPlugin);