Adding/expanding documentation

20 files changed, 162 insertions, 16 deletions

diff --git a/src/main/java/org/bukkit/ChatColor.java b/src/main/java/org/bukkit/ChatColor.java
index 2cef2590..67909c90 100644
--- a/src/main/java/org/bukkit/ChatColor.java
+++ b/src/main/java/org/bukkit/ChatColor.java
@@ -80,6 +80,10 @@ public enum ChatColor {
      */
     MAGIC('k', 0x10);
 
+    /**
+     * The special character which prefixes all chat colour codes. Use this if you need to dynamically
+     * convert colour codes from your custom format.
+     */
     public static final char COLOR_CHAR = '\u00A7';
     private static final Pattern STRIP_COLOR_PATTERN = Pattern.compile("(?i)" + String.valueOf(COLOR_CHAR) + "[0-9A-FK]");
 
diff --git a/src/main/java/org/bukkit/Effect.java b/src/main/java/org/bukkit/Effect.java
index 41ebf83b..cef6ddd9 100644
--- a/src/main/java/org/bukkit/Effect.java
+++ b/src/main/java/org/bukkit/Effect.java
@@ -11,19 +11,61 @@ import org.bukkit.potion.Potion;
  * A list of effects that the server is able to send to players.
  */
 public enum Effect {
+    /**
+     * An alternate click sound.
+     */
     CLICK2(1000, Type.SOUND),
+    /**
+     * A click sound.
+     */
     CLICK1(1001, Type.SOUND),
+    /**
+     * Sound of a bow firing.
+     */
     BOW_FIRE(1002, Type.SOUND),
+    /**
+     * Sound of a door opening/closing.
+     */
     DOOR_TOGGLE(1003, Type.SOUND),
+    /**
+     * Sound of fire being extinguished.
+     */
     EXTINGUISH(1004, Type.SOUND),
+    /**
+     * A song from a record. Needs the record item ID as additional info
+     */
     RECORD_PLAY(1005, Type.SOUND, Material.class),
+    /**
+     * Sound of ghast shrieking.
+     */
     GHAST_SHRIEK(1007, Type.SOUND),
+    /**
+     * Sound of ghast firing.
+     */
     GHAST_SHOOT(1008, Type.SOUND),
+    /**
+     * Sound of blaze firing.
+     */
     BLAZE_SHOOT(1009, Type.SOUND),
+    /**
+     * A visual smoke effect. Needs direction as additional info.
+     */
     SMOKE(2000, Type.VISUAL, BlockFace.class),
+    /**
+     * Visual effect of a block breaking. Needs block ID as additional info.
+     */
     STEP_SOUND(2001, Type.SOUND, Material.class),
+    /**
+     * Visual effect of a splash potion breaking. Needs potion data value as additional info.
+     */
     POTION_BREAK(2002, Type.VISUAL, Potion.class),
+    /**
+     * An ender eye signal; a visual effect.
+     */
     ENDER_SIGNAL(2003, Type.VISUAL),
+    /**
+     * The flames seen on a mobspawner; a visual effect.
+     */
     MOBSPAWNER_FLAMES(2004, Type.VISUAL);
 
     private final int id;
diff --git a/src/main/java/org/bukkit/Instrument.java b/src/main/java/org/bukkit/Instrument.java
index 0d19db67..f5fafe73 100644
--- a/src/main/java/org/bukkit/Instrument.java
+++ b/src/main/java/org/bukkit/Instrument.java
@@ -6,11 +6,26 @@ import com.google.common.collect.Maps;
 
 public enum Instrument {
 
-    PIANO(0x0), // All other
-    BASS_DRUM(0x1), // Stone
-    SNARE_DRUM(0x2), // Sand
-    STICKS(0x3), // Glass
-    BASS_GUITAR(0x4); // Wood
+    /**
+     * Piano is the standard instrument for a note block.
+     */
+    PIANO(0x0),
+    /**
+     * Bass drum is normally played when a note block is on top of a stone-like block
+     */
+    BASS_DRUM(0x1),
+    /**
+     * Snare drum is normally played when a note block is on top of a sandy block.
+     */
+    SNARE_DRUM(0x2),
+    /**
+     * Sticks are normally played when a note block is on top of a glass block.
+     */
+    STICKS(0x3),
+    /**
+     * Bass guitar is normally played when a note block is on top of a wooden block.
+     */
+    BASS_GUITAR(0x4);
 
     private final byte type;
     private final static Map<Byte, Instrument> BY_DATA = Maps.newHashMap();
@@ -19,10 +34,18 @@ public enum Instrument {
         this.type = (byte) type;
     }
 
+    /**
+     * @return The type ID of this instrument.
+     */
     public byte getType() {
         return this.type;
     }
 
+    /**
+     * Get an instrument by its type ID.
+     * @param type The type ID
+     * @return The instrument
+     */
     public static Instrument getByType(final byte type) {
         return BY_DATA.get(type);
     }
diff --git a/src/main/java/org/bukkit/TreeType.java b/src/main/java/org/bukkit/TreeType.java
index 92fe858b..f182102f 100644
--- a/src/main/java/org/bukkit/TreeType.java
+++ b/src/main/java/org/bukkit/TreeType.java
@@ -4,11 +4,32 @@ package org.bukkit;
  * Tree and organic structure types.
  */
 public enum TreeType {
+    /**
+     * Regular tree, no branches
+     */
     TREE,
+    /**
+     * Regular tree, extra tall with branches
+     */
     BIG_TREE,
+    /**
+     * Redwood tree, shaped like a pine tree
+     */
     REDWOOD,
+    /**
+     * Tall redwood tree with just a few leaves at the top
+     */
     TALL_REDWOOD,
+    /**
+     * Birch tree
+     */
     BIRCH,
+    /**
+     * Big red mushroom; short and fat
+     */
     RED_MUSHROOM,
+    /**
+     * Big brown mushroom; tall and umbrella-like
+     */
     BROWN_MUSHROOM
 }
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index daebf0bd..9beee093 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -921,6 +921,11 @@ public interface World extends PluginMessageRecipient, Metadatable {
             return id;
         }
 
+        /**
+         * Get an environment by ID
+         * @param id The ID of the environment
+         * @return The environment
+         */
         public static Environment getEnvironment(int id) {
             return lookup.get(id);
         }
diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index 99bc5630..f64a83be 100644
--- a/src/main/java/org/bukkit/block/Block.java
+++ b/src/main/java/org/bukkit/block/Block.java
@@ -151,6 +151,12 @@ public interface Block extends Metadatable {
      */
     void setData(byte data);
 
+    /**
+     * Sets the metadata for this block
+     *
+     * @param data New block specific metadata
+     * @param applyPhysics False to cancel physics from the changed block.
+     */
     void setData(byte data, boolean applyPhysics);
 
     /**
@@ -168,8 +174,23 @@ public interface Block extends Metadatable {
      */
     boolean setTypeId(int type);
 
+    /**
+     * Sets the type-id of this block
+     *
+     * @param type Type-Id to change this block to
+     * @param applyPhysics False to cancel physics on the changed block.
+     * @return whether the block was changed
+     */
     boolean setTypeId(int type, boolean applyPhysics);
 
+    /**
+     * Sets the type-id of this block
+     *
+     * @param type Type-Id to change this block to
+     * @param data The data value to change this block to
+     * @param applyPhysics False to cancel physics on the changed block
+     * @return whether the block was changed
+     */
     boolean setTypeIdAndData(int type, byte data, boolean applyPhysics);
 
     /**
diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
index cd5bcfbf..c727d0e0 100644
--- a/src/main/java/org/bukkit/block/BlockState.java
+++ b/src/main/java/org/bukkit/block/BlockState.java
@@ -146,7 +146,13 @@ public interface BlockState extends Metadatable {
      */
     boolean update(boolean force);
 
+    /**
+     * @return The data as a raw byte.
+     */
     public byte getRawData();
 
+    /**
+     * @param data The new data value for the block.
+     */
     public void setRawData(byte data);
 }
diff --git a/src/main/java/org/bukkit/block/PistonMoveReaction.java b/src/main/java/org/bukkit/block/PistonMoveReaction.java
index 42023b9a..c62294aa 100644
--- a/src/main/java/org/bukkit/block/PistonMoveReaction.java
+++ b/src/main/java/org/bukkit/block/PistonMoveReaction.java
@@ -4,8 +4,17 @@ import java.util.HashMap;
 import java.util.Map;
 
 public enum PistonMoveReaction {
+    /**
+     * Indicates that the block can be pushed or pulled.
+     */
     MOVE(0),
+    /**
+     * Indicates the block is fragile and will break if pushed on.
+     */
     BREAK(1),
+    /**
+     * Indicates that the block will resist being pushed or pulled.
+     */
     BLOCK(2);
 
     private int id;
@@ -20,10 +29,17 @@ public enum PistonMoveReaction {
         this.id = id;
     }
 
+    /**
+     * @return The ID of the move reaction
+     */
     public int getId() {
         return this.id;
     }
 
+    /**
+     * @param id An ID
+     * @return The move reaction with that ID
+     */
     public static PistonMoveReaction getById(int id) {
         return byId.get(id);
     }
diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
index d6035b8d..7eb01549 100644
--- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
+++ b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
@@ -14,6 +14,10 @@ import java.util.Map;
  * and returns the class.</li>
  * <li>A constructor that accepts a single {@link Map}&lt;{@link String}, {@link Object}>.</li>
  * </ul>
+ * In addition to implementing this interface, you must register the class with
+ * {@link ConfigurationSerialization#registerClass(Class)}.
+ * @see DelegateDeserialization
+ * @see SerializableAs
  */
 public interface ConfigurationSerializable {
     /**
diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java
index f2e7fe7f..b63d1c8b 100644
--- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java
+++ b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java
@@ -199,6 +199,7 @@ public class ConfigurationSerialization {
      *
      * @param clazz Class to register
      * @param alias Alias to register as
+     * @see SerializableAs
      */
     public static void registerClass(Class<? extends ConfigurationSerializable> clazz, String alias) {
         aliases.put(alias, clazz);
diff --git a/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java b/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java
index 81a8852a..437d7108 100644
--- a/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java
+++ b/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java
@@ -6,8 +6,8 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Represents a {@link ConfigurationSerializable} that will delegate all deserialization to another
- * {@link ConfigurationSerializable}
+ * Applies to a {@link ConfigurationSerializable} that will delegate all deserialization to another
+ * {@link ConfigurationSerializable}.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
diff --git a/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java b/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
index 361c6092..db69dfc8 100644
--- a/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
+++ b/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
@@ -10,8 +10,12 @@ import java.lang.annotation.Target;
  * If this is not present on a {@link ConfigurationSerializable} class, it will use the
  * fully qualified name of the class.
  * <p>
+ * This value will be stored in the configuration so that the configuration deserialization
+ * can determine what type it is.
+ * <p>
  * Using this annotation on any other class than a {@link ConfigurationSerializable} will
  * have no effect.
+ * @see ConfigurationSerialization#registerClass(Class, String)
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
diff --git a/src/main/java/org/bukkit/entity/Egg.java b/src/main/java/org/bukkit/entity/Egg.java
index e60c8025..2dcc00b9 100644
--- a/src/main/java/org/bukkit/entity/Egg.java
+++ b/src/main/java/org/bukkit/entity/Egg.java
@@ -1,6 +1,6 @@
 package org.bukkit.entity;
 
 /**
- * Represents an egg.
+ * Represents a thrown egg.
  */
 public interface Egg extends Projectile {}
diff --git a/src/main/java/org/bukkit/entity/EnderPearl.java b/src/main/java/org/bukkit/entity/EnderPearl.java
index 51e4f907..db18a90b 100644
--- a/src/main/java/org/bukkit/entity/EnderPearl.java
+++ b/src/main/java/org/bukkit/entity/EnderPearl.java
@@ -1,7 +1,7 @@
 package org.bukkit.entity;
 
 /**
- * Represents an Ender Pearl entity
+ * Represents a thrown Ender Pearl entity
  */
 public interface EnderPearl extends Projectile {
 
diff --git a/src/main/java/org/bukkit/entity/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java
index 53695e1c..e6b51e7f 100644
--- a/src/main/java/org/bukkit/entity/EntityType.java
+++ b/src/main/java/org/bukkit/entity/EntityType.java
@@ -18,7 +18,7 @@ public enum EntityType {
     ENDER_PEARL("ThrownEnderpearl", EnderPearl.class, 14),
     ENDER_SIGNAL("EyeOfEnderSignal", EnderSignal.class, 15),
     PRIMED_TNT("PrimedTnt", TNTPrimed.class, 20),
-    FALLING_BLOCK("FallingBlock", FallingSand.class, 21, false),
+    FALLING_BLOCK("FallingSand", FallingSand.class, 21, false),
     MINECART("Minecart", Minecart.class, 40),
     BOAT("Boat", Boat.class, 41),
     CREEPER("Creeper", Creeper.class, 50),
diff --git a/src/main/java/org/bukkit/entity/FallingSand.java b/src/main/java/org/bukkit/entity/FallingSand.java
index f876cb60..9af8b0d0 100644
--- a/src/main/java/org/bukkit/entity/FallingSand.java
+++ b/src/main/java/org/bukkit/entity/FallingSand.java
@@ -1,6 +1,6 @@
 package org.bukkit.entity;
 
 /**
- * Represents Falling Sand.
+ * Represents a falling block.
  */
 public interface FallingSand extends Entity {}
diff --git a/src/main/java/org/bukkit/entity/Fish.java b/src/main/java/org/bukkit/entity/Fish.java
index 50108053..dca77fce 100644
--- a/src/main/java/org/bukkit/entity/Fish.java
+++ b/src/main/java/org/bukkit/entity/Fish.java
@@ -1,6 +1,6 @@
 package org.bukkit.entity;
 
 /**
- * Represents a Fish.
+ * Represents a fishing hook.
  */
 public interface Fish extends Projectile {}
diff --git a/src/main/java/org/bukkit/entity/Painting.java b/src/main/java/org/bukkit/entity/Painting.java
index a6473ea6..ddc84524 100644
--- a/src/main/java/org/bukkit/entity/Painting.java
+++ b/src/main/java/org/bukkit/entity/Painting.java
@@ -2,6 +2,7 @@ package org.bukkit.entity;
 
 import org.bukkit.Art;
 import org.bukkit.block.BlockFace;
+import org.bukkit.event.painting.PaintingBreakEvent;
 import org.bukkit.material.Attachable;
 
 /**
@@ -29,7 +30,7 @@ public interface Painting extends Entity, Attachable {
      * @param art The new art
      * @param force If true, force the new art regardless of whether it fits at the current location
      *            Note that forcing it where it can't fit normally causes it to drop as an item unless you override
-     *            this by catching the PAINTING_BREAK event.
+     *            this by catching the {@link PaintingBreakEvent}.
      * @return False if force was false and the new art won't fit at the painting's current location
      */
     public boolean setArt(Art art, boolean force);
diff --git a/src/main/java/org/bukkit/entity/Slime.java b/src/main/java/org/bukkit/entity/Slime.java
index 88a6c0d9..cbf50c8e 100644
--- a/src/main/java/org/bukkit/entity/Slime.java
+++ b/src/main/java/org/bukkit/entity/Slime.java
@@ -6,13 +6,11 @@ package org.bukkit.entity;
 public interface Slime extends LivingEntity {
 
     /**
-     * @author Celtic Minstrel
      * @return The size of the slime
      */
     public int getSize();
 
     /**
-     * @author Celtic Minstrel
      * @param sz The new size of the slime.
      */
     public void setSize(int sz);
diff --git a/src/main/java/org/bukkit/entity/Snowball.java b/src/main/java/org/bukkit/entity/Snowball.java
index 47a86c49..8c6b4333 100644
--- a/src/main/java/org/bukkit/entity/Snowball.java
+++ b/src/main/java/org/bukkit/entity/Snowball.java
@@ -1,6 +1,6 @@
 package org.bukkit.entity;
 
 /**
- * Implements a snowball.
+ * Represents a snowball.
  */
 public interface Snowball extends Projectile {}