From ac51658471302814c3d40aaff1f144f10901958a Mon Sep 17 00:00:00 2001 From: Celtic Minstrel Date: Sun, 26 Feb 2012 12:13:30 -0500 Subject: Adding/expanding documentation --- src/main/java/org/bukkit/ChatColor.java | 4 +++ src/main/java/org/bukkit/Effect.java | 42 ++++++++++++++++++++++ src/main/java/org/bukkit/Instrument.java | 33 ++++++++++++++--- src/main/java/org/bukkit/TreeType.java | 21 +++++++++++ src/main/java/org/bukkit/World.java | 5 +++ src/main/java/org/bukkit/block/Block.java | 21 +++++++++++ src/main/java/org/bukkit/block/BlockState.java | 6 ++++ .../java/org/bukkit/block/PistonMoveReaction.java | 16 +++++++++ .../serialization/ConfigurationSerializable.java | 4 +++ .../serialization/ConfigurationSerialization.java | 1 + .../serialization/DelegateDeserialization.java | 4 +-- .../serialization/SerializableAs.java | 4 +++ src/main/java/org/bukkit/entity/Egg.java | 2 +- src/main/java/org/bukkit/entity/EnderPearl.java | 2 +- src/main/java/org/bukkit/entity/EntityType.java | 2 +- src/main/java/org/bukkit/entity/FallingSand.java | 2 +- src/main/java/org/bukkit/entity/Fish.java | 2 +- src/main/java/org/bukkit/entity/Painting.java | 3 +- src/main/java/org/bukkit/entity/Slime.java | 2 -- src/main/java/org/bukkit/entity/Snowball.java | 2 +- 20 files changed, 162 insertions(+), 16 deletions(-) (limited to 'src/main/java') 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 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. *
  • A constructor that accepts a single {@link Map}<{@link String}, {@link Object}>.
    • * + * 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 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. *

    + * This value will be stored in the configuration so that the configuration deserialization + * can determine what type it is. + *

    * 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 {} -- cgit v1.2.3