Pulling all pending Bukkit-JavaDoc changes

src/main/java/org/bukkit/DyeColor.java

@@ -10,67 +10,67 @@
 public enum DyeColor {
 
     /**
-     * Represents white dye
+     * Represents white dye.
      */
     WHITE(0x0, 0xF, Color.WHITE, Color.fromRGB(0xF0F0F0)),
     /**
-     * Represents orange dye
+     * Represents orange dye.
      */
     ORANGE(0x1, 0xE, Color.fromRGB(0xD87F33), Color.fromRGB(0xEB8844)),
     /**
-     * Represents magenta dye
+     * Represents magenta dye.
      */
     MAGENTA(0x2, 0xD, Color.fromRGB(0xB24CD8), Color.fromRGB(0xC354CD)),
     /**
-     * Represents light blue dye
+     * Represents light blue dye.
      */
     LIGHT_BLUE(0x3, 0xC, Color.fromRGB(0x6699D8), Color.fromRGB(0x6689D3)),
     /**
-     * Represents yellow dye
+     * Represents yellow dye.
      */
     YELLOW(0x4, 0xB, Color.fromRGB(0xE5E533), Color.fromRGB(0xDECF2A)),
     /**
-     * Represents lime dye
+     * Represents lime dye.
      */
     LIME(0x5, 0xA, Color.fromRGB(0x7FCC19), Color.fromRGB(0x41CD34)),
     /**
-     * Represents pink dye
+     * Represents pink dye.
      */
     PINK(0x6, 0x9, Color.fromRGB(0xF27FA5), Color.fromRGB(0xD88198)),
     /**
-     * Represents gray dye
+     * Represents gray dye.
      */
     GRAY(0x7, 0x8, Color.fromRGB(0x4C4C4C), Color.fromRGB(0x434343)),
     /**
-     * Represents silver dye
+     * Represents silver dye.
      */
     SILVER(0x8, 0x7, Color.fromRGB(0x999999), Color.fromRGB(0xABABAB)),
     /**
-     * Represents cyan dye
+     * Represents cyan dye.
      */
     CYAN(0x9, 0x6, Color.fromRGB(0x4C7F99), Color.fromRGB(0x287697)),
     /**
-     * Represents purple dye
+     * Represents purple dye.
      */
     PURPLE(0xA, 0x5, Color.fromRGB(0x7F3FB2), Color.fromRGB(0x7B2FBE)),
     /**
-     * Represents blue dye
+     * Represents blue dye.
      */
     BLUE(0xB, 0x4, Color.fromRGB(0x334CB2), Color.fromRGB(0x253192)),
     /**
-     * Represents brown dye
+     * Represents brown dye.
      */
     BROWN(0xC, 0x3, Color.fromRGB(0x664C33), Color.fromRGB(0x51301A)),
     /**
-     * Represents green dye
+     * Represents green dye.
      */
     GREEN(0xD, 0x2, Color.fromRGB(0x667F33), Color.fromRGB(0x3B511A)),
     /**
-     * Represents red dye
+     * Represents red dye.
      */
     RED(0xE, 0x1, Color.fromRGB(0x993333), Color.fromRGB(0xB3312C)),
     /**
-     * Represents black dye
+     * Represents black dye.
      */
     BLACK(0xF, 0x0, Color.fromRGB(0x191919), Color.fromRGB(0x1E1B1B));
 
@@ -129,7 +129,7 @@ public byte getDyeData() {
     }
 
     /**
-     * Gets the color that this dye represents
+     * Gets the color that this dye represents.
      *
      * @return The {@link Color} that this dye represents
      */
@@ -138,7 +138,7 @@ public Color getColor() {
     }
 
     /**
-     * Gets the firework color that this dye represents
+     * Gets the firework color that this dye represents.
      *
      * @return The {@link Color} that this dye represents
      */
@@ -199,7 +199,7 @@ public static DyeColor getByDyeData(final byte data) {
     }
 
     /**
-     * Gets the DyeColor with the given color value
+     * Gets the DyeColor with the given color value.
      *
      * @param color Color value to get the dye by
      * @return The {@link DyeColor} representing the given value, or null if
@@ -210,7 +210,7 @@ public static DyeColor getByColor(final Color color) {
     }
 
     /**
-     * Gets the DyeColor with the given firework color value
+     * Gets the DyeColor with the given firework color value.
      *
      * @param color Color value to get dye by
      * @return The {@link DyeColor} representing the given value, or null if

src/main/java/org/bukkit/SkullType.java

@@ -1,7 +1,7 @@
 package org.bukkit;
 
 /**
- * Represents the types of skulls
+ * Represents the different types of skulls.
  */
 public enum SkullType {
     SKELETON,

src/main/java/org/bukkit/entity/Player.java

@@ -755,7 +755,7 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
     /**
      * Sets the players current saturation level
      *
-     * @param value Exhaustion level
+     * @param value Saturation level
      */
     public void setSaturation(float value);
 

src/main/java/org/bukkit/event/entity/EntityShootBowEvent.java

@@ -30,10 +30,9 @@ public LivingEntity getEntity() {
     }
 
     /**
-     * Gets the bow ItemStack used to fire the arrow; is null if the shooter
-     * is a skeleton
+     * Gets the bow ItemStack used to fire the arrow.
      *
-     * @return the bow involved in this event, or null
+     * @return the bow involved in this event
      */
     public ItemStack getBow() {
         return bow;

src/main/java/org/bukkit/event/player/PlayerAchievementAwardedEvent.java

@@ -20,7 +20,7 @@ public PlayerAchievementAwardedEvent(Player player, Achievement achievement) {
 
     /**
      * Gets the Achievement being awarded.
-     * 
+     *
      * @return the achievement being awarded
      */
     public Achievement getAchievement() {

src/main/java/org/bukkit/plugin/Plugin.java

@@ -169,11 +169,11 @@ public interface Plugin extends TabExecutor {
     public ChunkGenerator getDefaultWorldGenerator(String worldName, String id);
 
     /**
-     * Returns the primary logger associated with this server instance. The
+     * Returns the plugin logger associated with this server's logger. The
      * returned logger automatically tags all log messages with the plugin's
      * name.
      *
-     * @return Logger associated with this server
+     * @return Logger associated with this plugin
      */
     public Logger getLogger();
 

src/main/java/org/bukkit/plugin/PluginDescriptionFile.java

@@ -617,6 +617,7 @@ public String getPrefix() {
      *  # Having an empty declaration is useful for defining the description, permission, and messages from a configuration dynamically
      *  apocalypse:
      *</pre></blockquote>
+     * Note: command names may not have a colon in their name.
      *
      * @return the commands this plugin will register
      */

src/main/java/org/bukkit/plugin/java/JavaPlugin.java

@@ -417,14 +417,15 @@ public String toString() {
      * resided in a different jar / classloader.
      *
      * @param clazz the class desired
-     * @return the plugin that provides and implements said class, or null
-     *     if called from an inconsistent static initialization block
+     * @return the plugin that provides and implements said class
      * @throws IllegalArgumentException if clazz is null
      * @throws IllegalArgumentException if clazz does not extend {@link
      *     JavaPlugin}
-     * @throws IllegalArgumentException if clazz was not provided by a
-     *     plugin, for example, if called with
+     * @throws IllegalStateException if clazz was not provided by a plugin,
+     *     for example, if called with
      *     <code>JavaPlugin.getPlugin(JavaPlugin.class)</code>
+     * @throws IllegalStateException if called from the static initializer for
+     *     given JavaPlugin
      * @throws ClassCastException if plugin that provided the class does not
      *     extend the class
      */
@@ -445,9 +446,14 @@ public static <T extends JavaPlugin> T getPlugin(Class<T> clazz) {
     }
 
     /**
-     * This method provides fast access to the plugin that has {@link
-     * #getProvidingPlugin(Class) provided} the given plugin class, which is
-     * usually the plugin that implemented it.
+     * This method provides fast access to the plugin that has provided the
+     * given class.
+     *
+     * @throws IllegalArgumentException if the class is not provided by a
+     *     JavaPlugin
+     * @throws IllegalArgumentException if class is null
+     * @throws IllegalStateException if called from the static initializer for
+     *     given JavaPlugin
      */
     public static JavaPlugin getProvidingPlugin(Class<?> clazz) {
         Validate.notNull(clazz, "Null class cannot have a plugin");