Clean up Javadocs for the blocks.* package.

src/legacy/java/com/sk89q/worldedit/masks/FuzzyBlockMask.java

@@ -22,6 +22,7 @@ package com.sk89q.worldedit.masks;
 import com.sk89q.worldedit.EditSession;
 import com.sk89q.worldedit.Vector;
 import com.sk89q.worldedit.blocks.BaseBlock;
+import com.sk89q.worldedit.blocks.Blocks;
 
 import java.util.HashSet;
 import java.util.Set;
@@ -59,6 +60,6 @@ public class FuzzyBlockMask extends AbstractMask {
     @Override
     public boolean matches(EditSession editSession, Vector pos) {
         BaseBlock compare = new BaseBlock(editSession.getBlockType(pos), editSession.getBlockData(pos));
-        return BaseBlock.containsFuzzy(filter, compare);
+        return Blocks.containsFuzzy(filter, compare);
     }
 }

src/main/java/com/sk89q/worldedit/blocks/BaseBlock.java

@@ -24,37 +24,49 @@ import com.sk89q.jnbt.StringTag;
 import com.sk89q.jnbt.Tag;
 import com.sk89q.worldedit.CuboidClipboard.FlipDirection;
 import com.sk89q.worldedit.foundation.Block;
-import com.sk89q.worldedit.world.DataException;
+import com.sk89q.worldedit.function.mask.Mask;
+import com.sk89q.worldedit.world.registry.WorldData;
 
+import javax.annotation.Nullable;
 import java.util.Collection;
 
 /**
- * Represents a mutable copy of a block that is not tied to any 'real' block in a world.
+ * Represents a mutable "snapshot" of a block.
- * A single instance of this can be set to multiple locations and each location would
+ *
- * have a copy of this instance's data.
+ * <p>An instance of this block contains all the information needed to
- * </p>
+ * accurately reproduce the block, provided that the instance was
- * Implementations can and should extend this class to allow native implementations
+ * made correctly. In some implementations, it may not be possible to get a
- * of NBT data handling, primarily for performance reasons. Subclasses can only convert
+ * snapshot of blocks correctly, so, for example, the NBT data for a block
- * from and to WorldEdit-native NBT structures when absolutely necessary (a.k.a. when
+ * may be missing.</p>
- * {@link #getNbtData()} and {@link #setNbtData(CompoundTag)} are called). When
+ *
- * overriding the NBT methods, {@link #getNbtId()} should be overridden too, otherwise
+ * <p>This class identifies blocks using an integer ID. However, IDs for
- * the default implementation will invoke {@link #getNbtData()}, a potentially costly
+ * a given block may differ between worlds so it is important that users of
- * operation when it is not needed. Implementations may want to cache converted NBT data
+ * this class convert the ID from one "world space" to another "world space,"
- * structures if possible.
+ * a task that that is assisted with by working with the source and
+ * destination {@link WorldData} instances. Numeric IDs are utilized because
+ * they are more space efficient to store, and it also implies that internal
+ * uses of this class (i.e. history, etc.) do not need to worry about
+ * interning block string IDs.</p>
+ *
+ * <p>A peculiar detail of this class is that it accepts {@code -1} as a
+ * valid data value. This is due to legacy reasons: WorldEdit uses -1
+ * as a "wildcard" block value, even though a {@link Mask} would be
+ * more appropriate.</p>
  */
 public class BaseBlock extends Block implements TileEntityBlock {
 
     /**
-     * Indicates the highest possible block ID (inclusive) that can be used. This value
+     * Indicates the highest possible block ID (inclusive) that can be used.
-     * is subject to change depending on the implementation, but internally this class
+     * This value is subject to change depending on the implementation, but
-     * only supports a range of 4096 IDs (for space reasons), which coincides with the
+     * internally this class only supports a range of 4096 IDs (for space
-     * number of possible IDs that official Minecraft supports as of version 1.3.
+     * reasons), which coincides with the number of possible IDs that official
+     * Minecraft supports as of version 1.7.
      */
     public static final int MAX_ID = 4095;
 
     /**
-     * Indicates the maximum data value (inclusive) that can be used. Minecraft 1.4 may
+     * Indicates the maximum data value (inclusive) that can be used. A future
-     * abolish usage of data values and this value may be removed in the future.
+     * version of Minecraft may abolish block data values.
      */
     public static final int MAX_DATA = 15;
 
@@ -63,6 +75,7 @@ public class BaseBlock extends Block implements TileEntityBlock {
 
     private short id;
     private short data;
+    @Nullable
     private CompoundTag nbtData;
 
     /**
@@ -90,17 +103,13 @@ public class BaseBlock extends Block implements TileEntityBlock {
     }
 
     /**
-     * Construct a block with the given ID, data value, and NBT data structure.
+     * Construct a block with the given ID, data value and NBT data structure.
      *
      * @param id ID value
      * @param data data value
-     * @param nbtData NBT data
+     * @param nbtData NBT data, which may be null
-     * @throws DataException if possibly the data is invalid
-     * @see #setId(int)
-     * @see #setData(int)
-     * @see #setNbtData(CompoundTag)
      */
-    public BaseBlock(int id, int data, CompoundTag nbtData) {
+    public BaseBlock(int id, int data, @Nullable CompoundTag nbtData) {
         setId(id);
         setData(data);
         setNbtData(nbtData);
@@ -236,11 +245,13 @@ public class BaseBlock extends Block implements TileEntityBlock {
         }
     }
 
+    @Nullable
     @Override
     public CompoundTag getNbtData() {
         return nbtData;
     }
 
+    @Nullable
     @Override
     public void setNbtData(CompoundTag nbtData) {
         this.nbtData = nbtData;
@@ -275,9 +286,11 @@ public class BaseBlock extends Block implements TileEntityBlock {
 
     /**
      * Rotate this block 90 degrees.
-     * 
+     *
      * @return new data value
+     * @deprecated Use {@link BlockData#rotate90(int, int)}
      */
+    @Deprecated
     public int rotate90() {
         int newData = BlockData.rotate90(getType(), getData());
         setData(newData);
@@ -288,7 +301,9 @@ public class BaseBlock extends Block implements TileEntityBlock {
      * Rotate this block -90 degrees.
      * 
      * @return new data value
+     * @deprecated Use {@link BlockData#rotate90Reverse(int, int)}
      */
+    @Deprecated
     public int rotate90Reverse() {
         int newData = BlockData.rotate90Reverse(getType(), getData());
         setData((short) newData);
@@ -300,7 +315,9 @@ public class BaseBlock extends Block implements TileEntityBlock {
      *
      * @param increment 1 for forward, -1 for backward
      * @return new data value
+     * @deprecated Use {@link BlockData#cycle(int, int, int)}
      */
+    @Deprecated
     public int cycleData(int increment) {
         int newData = BlockData.cycle(getType(), getData(), increment);
         setData((short) newData);
@@ -311,7 +328,9 @@ public class BaseBlock extends Block implements TileEntityBlock {
      * Flip this block.
      * 
      * @return this block
+     * @deprecated Use {@link BlockData#flip(int, int)}
      */
+    @Deprecated
     public BaseBlock flip() {
         setData((short) BlockData.flip(getType(), getData()));
         return this;
@@ -322,7 +341,9 @@ public class BaseBlock extends Block implements TileEntityBlock {
      * 
      * @param direction direction to flip in
      * @return this block
+     * @deprecated Use {@link BlockData#flip(int, int, FlipDirection)}
      */
+    @Deprecated
     public BaseBlock flip(FlipDirection direction) {
         setData((short) BlockData.flip(getType(), getData(), direction));
         return this;
@@ -356,8 +377,6 @@ public class BaseBlock extends Block implements TileEntityBlock {
     }
 
     /**
-     * @param iter
-     * @return
      * @deprecated This method is silly, use {@link #containsFuzzy(java.util.Collection, BaseBlock)} instead.
      */
     @Deprecated
@@ -370,14 +389,12 @@ public class BaseBlock extends Block implements TileEntityBlock {
         return false;
     }
 
+    /**
+     * @deprecated Use {@link Blocks#containsFuzzy(Collection, BaseBlock)}
+     */
+    @Deprecated
     public static boolean containsFuzzy(Collection<BaseBlock> collection, BaseBlock o) {
-        // allow masked data in the searchBlocks to match various types
+        return Blocks.containsFuzzy(collection, o);
-        for (BaseBlock b : collection) {
-            if (b.equalsFuzzy(o)) {
-                return true;
-            }
-        }
-        return false;
     }
 
     @Override

src/main/java/com/sk89q/worldedit/blocks/BaseItem.java

@@ -23,10 +23,10 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Represents an item, without an amount value. See {@link BaseItemStack} for an instance
+ * Represents an item, without an amount value. See {@link BaseItemStack}
- * with stack amount information.
+ * for an instance with stack amount information.
  *
- * @author sk89q
+ * <p>This class may be removed in the future.</p>
  */
 public class BaseItem {
     

src/main/java/com/sk89q/worldedit/blocks/BaseItemStack.java

@@ -22,12 +22,10 @@ package com.sk89q.worldedit.blocks;
 /**
  * Represents a stack of BaseItems.
  *
- * @author sk89q
+ * <p>This class may be removed in the future.</p>
  */
 public class BaseItemStack extends BaseItem {
-    /**
+
-     * Amount of an item.
-     */
     private int amount = 1;
 
     /**

src/main/java/com/sk89q/worldedit/blocks/BlockData.java

@@ -23,8 +23,6 @@ import com.sk89q.worldedit.CuboidClipboard.FlipDirection;
 
 /**
  * Block data related classes.
- *
- * @author sk89q
  */
 public final class BlockData {
 
@@ -34,9 +32,9 @@ public final class BlockData {
     /**
      * Rotate a block's data value 90 degrees (north->east->south->west->north);
      * 
-     * @param type
+     * @param type the type ID of the bock
-     * @param data
+     * @param data the data ID of the block
-     * @return
+     * @return the new data value
      */
     public static int rotate90(int type, int data) {
         switch (type) {
@@ -251,10 +249,10 @@ public final class BlockData {
 
     /**
      * Rotate a block's data value -90 degrees (north<-east<-south<-west<-north);
-     * 
+     *
-     * @param type
+     * @param type the type ID of the bock
-     * @param data
+     * @param data the data ID of the block
-     * @return
+     * @return the new data value
      */
     public static int rotate90Reverse(int type, int data) {
         // case ([0-9]+): return ([0-9]+) -> case \2: return \1
@@ -470,10 +468,10 @@ public final class BlockData {
 
     /**
      * Flip a block's data value.
-     * 
+     *
-     * @param type
+     * @param type the type ID of the bock
-     * @param data
+     * @param data the data ID of the block
-     * @return
+     * @return the new data value
      */
     public static int flip(int type, int data) {
         return rotate90(type, rotate90(type, data));
@@ -481,11 +479,11 @@ public final class BlockData {
 
     /**
      * Flip a block's data value.
-     * 
+     *
-     * @param type
+     * @param type the type ID of the bock
-     * @param data
+     * @param data the data ID of the block
-     * @param direction
+     * @param direction the direction to flip
-     * @return
+     * @return the new data value
      */
     public static int flip(int type, int data, FlipDirection direction) {
         int flipX = 0;
@@ -970,14 +968,6 @@ public final class BlockData {
         }
     }
 
-    /**
-     * Better modulo, not just remainder.
-     */
-    private static int mod(int x, int y) {
-        int res = x % y;
-        return res < 0 ? res + y : res;
-    }
-
     /**
      * Returns the data value for the next color of cloth in the rainbow. This
      * should not be used if you want to just increment the data value.
@@ -1010,8 +1000,9 @@ public final class BlockData {
     /**
      * Returns the data value for the previous ext color of cloth in the rainbow.
      * This should not be used if you want to just increment the data value.
-     * @param data
+     *
-     * @return
+     * @param data the data value
+     * @return the new data value
      */
     public static int prevClothColor(int data) {
         switch (data) {
@@ -1035,4 +1026,13 @@ public final class BlockData {
 
         return ClothColor.ID.WHITE;
     }
+
+    /**
+     * Better modulo, not just remainder.
+     */
+    private static int mod(int x, int y) {
+        int res = x % y;
+        return res < 0 ? res + y : res;
+    }
+
 }

src/main/java/com/sk89q/worldedit/blocks/BlockType.java

@@ -22,7 +22,15 @@ package com.sk89q.worldedit.blocks;
 import com.sk89q.util.StringUtil;
 import com.sk89q.worldedit.PlayerDirection;
 
-import java.util.*;
+import javax.annotation.Nullable;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Random;
+import java.util.Set;
+
+import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
  * Block types.
@@ -229,8 +237,9 @@ public enum BlockType {
     /**
      * Construct the type.
      *
-     * @param id
+     * @param id the ID of the block
-     * @param name
+     * @param name the name of the block
+     * @param lookupKey a name to reference the block by
      */
     BlockType(int id, String name, String lookupKey) {
         this.id = id;
@@ -241,8 +250,9 @@ public enum BlockType {
     /**
      * Construct the type.
      *
-     * @param id
+     * @param id the ID of the block
-     * @param name
+     * @param name the name of the block
+     * @param lookupKeys an array of keys to reference the block by
      */
     BlockType(int id, String name, String... lookupKeys) {
         this.id = id;
@@ -253,9 +263,10 @@ public enum BlockType {
     /**
      * Return type from ID. May return null.
      *
-     * @param id
+     * @param id the type ID
-     * @return
+     * @return a block type, otherwise null
      */
+    @Nullable
     public static BlockType fromID(int id) {
         return ids.get(id);
     }
@@ -263,9 +274,10 @@ public enum BlockType {
     /**
      * Return type from name. May return null.
      *
-     * @param name
+     * @param name the name to search
-     * @return
+     * @return a block type or null
      */
+    @Nullable
     public static BlockType lookup(String name) {
         return lookup(name, true);
     }
@@ -273,10 +285,11 @@ public enum BlockType {
     /**
      * Return type from name. May return null.
      *
-     * @param name
+     * @param name the name (or ID) of a block
-     * @param fuzzy
+     * @param fuzzy true to for a fuzzy search on the block name
-     * @return
+     * @return a block type or null
      */
+    @Nullable
     public static BlockType lookup(String name, boolean fuzzy) {
         try {
             return fromID(Integer.parseInt(name));
@@ -285,8 +298,8 @@ public enum BlockType {
         }
     }
 
-    private static Map<Integer, BaseBlock> itemBlockMapping = new HashMap<Integer, BaseBlock>();
+    private static final Map<Integer, BaseBlock> itemBlockMapping = new HashMap<Integer, BaseBlock>();
-    private static Map<Integer, BaseBlock> dataItemBlockMapping = new HashMap<Integer, BaseBlock>();
+    private static final Map<Integer, BaseBlock> dataItemBlockMapping = new HashMap<Integer, BaseBlock>();
     static {
         for (int data = 0; data < 16; ++data) {
             dataItemBlockMapping.put(typeDataKey(BlockID.DIRT, data), new BaseBlock(BlockID.DIRT, data));
@@ -328,6 +341,14 @@ public enum BlockType {
         itemBlockMapping.put(ItemID.COMPARATOR, new BaseBlock(BlockID.COMPARATOR_OFF, -1));
     }
 
+    /**
+     * Get the equivalent block for an item.
+     *
+     * @param typeId the type ID of the block
+     * @param data the data valuie of the block
+     * @return a block or null
+     */
+    @Nullable
     public static BaseBlock getBlockForItem(int typeId, int data) {
         final BaseBlock block = itemBlockMapping.get(typeId);
 
@@ -341,7 +362,7 @@ public enum BlockType {
     /**
      * Get block numeric ID.
      *
-     * @return
+     * @return the block ID
      */
     public int getID() {
         return id;
@@ -350,7 +371,7 @@ public enum BlockType {
     /**
      * Get user-friendly block name.
      *
-     * @return
+     * @return the block name
      */
     public String getName() {
         return name;
@@ -415,19 +436,21 @@ public enum BlockType {
     }
 
     /**
-     * Checks to see whether a block should be placed last.
+     * Checks to see whether a block should be placed last (when reordering
+     * blocks that are placed).
      *
-     * @param id
+     * @param id the block ID
-     * @return
+     * @return true if the block should be placed last
      */
     public static boolean shouldPlaceLast(int id) {
         return shouldPlaceLast.contains(id);
     }
 
     /**
-     * Checks to see whether this block should be placed last.
+     * Checks to see whether this block should be placed last (when reordering
+     * blocks that are placed)
      *
-     * @return
+     * @return true if the block should be placed last
      */
     public boolean shouldPlaceLast() {
         return shouldPlaceLast.contains(id);
@@ -454,8 +477,8 @@ public enum BlockType {
      *
      * This applies to blocks that can be attached to other blocks that have an attachment.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return whether the block is in the final queue
      */
     public static boolean shouldPlaceFinal(int id) {
         return shouldPlaceFinal.contains(id);
@@ -522,8 +545,8 @@ public enum BlockType {
     /**
      * Checks whether a block can be passed through.
      *
-     * @param id
+     * @param id the ID of the block
-     * @return
+     * @return true if the block can be passed through
      */
     public static boolean canPassThrough(int id) {
         return canPassThrough.contains(id);
@@ -532,9 +555,9 @@ public enum BlockType {
     /**
      * Checks whether a block can be passed through.
      *
-     * @param id
+     * @param id the ID of the block
-     * @param data
+     * @param data the data value of the block
-     * @return
+     * @return true if the block can be passed through
      */
     public static boolean canPassThrough(int id, int data) {
         return canPassThrough.contains(-16*id-data) || canPassThrough.contains(id);
@@ -543,17 +566,18 @@ public enum BlockType {
     /**
      * Checks whether a block can be passed through.
      *
-     * @param block
+     * @param block the block
-     * @return
+     * @return true if the block can be passed through
      */
     public static boolean canPassThrough(BaseBlock block) {
+        checkNotNull(block);
         return canPassThrough(block.getId(), block.getData());
     }
 
     /**
-     * Checks whether a block can be passed through.
+     * Checks whether the block type can be passed through.
      *
-     * @return
+     * @return whether the block can be passed through
      */
     public boolean canPassThrough() {
         return canPassThrough.contains(id);
@@ -622,9 +646,9 @@ public enum BlockType {
     /**
      * Returns the y offset a player falls to when falling onto the top of a block at xp+0.5/zp+0.5.
      *
-     * @param id
+     * @param id the block ID
-     * @param data
+     * @param data the block data value
-     * @return
+     * @return the y offset
      */
     public static double centralTopLimit(int id, int data) {
         if (centralTopLimit.containsKey(-16*id-data))
@@ -639,17 +663,18 @@ public enum BlockType {
     /**
      * Returns the y offset a player falls to when falling onto the top of a block at xp+0.5/zp+0.5.
      *
-     * @param block
+     * @param block the block
-     * @return
+     * @return the y offset
      */
     public static double centralTopLimit(BaseBlock block) {
+        checkNotNull(block);
         return centralTopLimit(block.getId(), block.getData());
     }
 
     /**
      * Returns the y offset a player falls to when falling onto the top of a block at xp+0.5/zp+0.5.
      *
-     * @return
+     * @return the y offset
      */
     public double centralTopLimit() {
         if (centralTopLimit.containsKey(id))
@@ -771,8 +796,8 @@ public enum BlockType {
     /**
      * Returns true if the block uses its data value.
      *
-     * @param id
+     * @param id the type ID
-     * @return
+     * @return true if the block type uses its data value
      */
     public static boolean usesData(int id) {
         return usesData.contains(id);
@@ -781,7 +806,7 @@ public enum BlockType {
     /**
      * Returns true if the block uses its data value.
      *
-     * @return
+     * @return true if this block type uses its data value
      */
     public boolean usesData() {
         return usesData.contains(id);
@@ -806,8 +831,8 @@ public enum BlockType {
     /**
      * Returns true if the block is a container block.
      *
-     * @param id
+     * @param id the block ID
-     * @return
+     * @return true if the block is a container
      */
     public static boolean isContainerBlock(int id) {
         return isContainerBlock.contains(id);
@@ -816,7 +841,7 @@ public enum BlockType {
     /**
      * Returns true if the block is a container block.
      *
-     * @return
+     * @return true if the block is a container block
      */
     public boolean isContainerBlock() {
         return isContainerBlock.contains(id);
@@ -861,19 +886,19 @@ public enum BlockType {
     }
 
     /**
-     * Returns true if a block uses redstone in some way.
+     * Returns true if a block uses Redstone in some way.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return true if the block uses Redstone
      */
     public static boolean isRedstoneBlock(int id) {
         return isRedstoneBlock.contains(id);
     }
 
     /**
-     * Returns true if a block uses redstone in some way.
+     * Returns true if a block uses Redstone in some way.
      *
-     * @return
+     * @return true if the block uses Redstone
      */
     public boolean isRedstoneBlock() {
         return isRedstoneBlock.contains(id);
@@ -894,21 +919,23 @@ public enum BlockType {
     }
 
     /**
-     * Returns true if a block can transfer redstone.
+     * Returns true if a block can transfer Redstone.
-     * Made this since isRedstoneBlock was getting big.
      *
-     * @param id
+     * <p>This was made since {@link #isRedstoneBlock} was getting big.</p>
-     * @return
+     *
+     * @param id the type ID of the block
+     * @return true if the block can transfer redstone
      */
     public static boolean canTransferRedstone(int id) {
         return canTransferRedstone.contains(id);
     }
 
     /**
-     * Returns true if a block can transfer redstone.
+     * Returns true if a block can transfer Redstone.
-     * Made this since isRedstoneBlock was getting big.
      *
-     * @return
+     * <p>This was made since {@link #isRedstoneBlock} was getting big.</p>
+     *
+     * @return true if the block can transfer redstone
      */
     public boolean canTransferRedstone() {
         return canTransferRedstone.contains(id);
@@ -935,19 +962,19 @@ public enum BlockType {
     }
 
     /**
-     * Yay for convenience methods.
+     * Returns whether the block is a Redstone source.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return true if the block is a Redstone source
      */
     public static boolean isRedstoneSource(int id) {
         return isRedstoneSource.contains(id);
     }
 
     /**
-     * Yay for convenience methods.
+     * Returns whether the block is a Redstone source.
      *
-     * @return
+     * @return true if the block is a Redstone source
      */
     public boolean isRedstoneSource() {
         return isRedstoneSource.contains(id);
@@ -965,19 +992,19 @@ public enum BlockType {
     }
 
     /**
-     * Checks if the id is that of one of the rail types
+     * Checks if the block is that of one of the rail types.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return true if the block is a rail block
      */
     public static boolean isRailBlock(int id) {
         return isRailBlock.contains(id);
     }
 
     /**
-     * Checks if the id is that of one of the rail types
+     * Checks if the block is that of one of the rail types
      *
-     * @return
+     * @return true if the block is a rail block
      */
     public boolean isRailBlock() {
         return isRailBlock.contains(id);
@@ -1018,10 +1045,10 @@ public enum BlockType {
     }
 
     /**
-     * Checks if the block type is naturally occuring
+     * Checks if the block type is naturally occurring.
      *
-     * @param id      ID of the block
+     * @param id the type ID of the block
-     * @return true if the block type is naturally occuring
+     * @return true if the block type is naturally occurring
      * @deprecated Use {@link #isNaturalTerrainBlock(int, int)}
      */
     @Deprecated
@@ -1030,30 +1057,30 @@ public enum BlockType {
     }
 
     /**
-     * Checks if the block type is naturally occuring
+     * Checks if the block type is naturally occurring
      *
-     * @param id      ID of the block
+     * @param id the type ID of the block
-     * @param data    Data value of the block
+     * @param data data value of the block
-     * @return true if the block type is naturally occuring
+     * @return true if the block type is naturally occurring
      */
     public static boolean isNaturalTerrainBlock(int id, int data) {
         return isNaturalTerrainBlock.contains(-16*id-data) || isNaturalTerrainBlock.contains(id);
     }
 
     /**
-     * Checks if the block type is naturally occuring
+     * Checks if the block type is naturally occurring
      *
-     * @param block The block
+     * @param block the block
-     * @return true if the block type is naturally occuring
+     * @return true if the block type is naturally occurring
      */
     public static boolean isNaturalTerrainBlock(BaseBlock block) {
         return isNaturalTerrainBlock(block.getId(), block.getData());
     }
 
     /**
-     * Checks if the block type is naturally occuring
+     * Checks if the block type is naturally occurring
      *
-     * @return true if the block type is naturally occuring
+     * @return true if the block type is naturally occurring
      */
     public boolean isNaturalTerrainBlock() {
         return isNaturalTerrainBlock.contains(id);
@@ -1087,10 +1114,10 @@ public enum BlockType {
     }
 
     /**
-     * Checks if the block type emits light
+     * Checks if the block type emits light.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return true if the block emits light
      */
     public static boolean emitsLight(int id) {
         return emitsLight.contains(id);
@@ -1197,10 +1224,10 @@ public enum BlockType {
     }
 
     /**
-     * Checks if the block type lets light through
+     * Checks if the block type lets light through.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return true if the block type lets light through
      */
     public static boolean isTranslucent(int id) {
         return isTranslucent.contains(id);
@@ -1409,10 +1436,11 @@ public enum BlockType {
      * dropped, a block with a BaseItemStack of type AIR and size 0 will be returned.
      * If the block should not be destroyed (i.e. bedrock), null will be returned.
      *
-     * @param type
+     * @param type the type of of the block
-     * @param data
+     * @param data the data value of the block
-     * @return
+     * @return the item or null
      */
+    @Nullable
     public static BaseItem getBlockBagItem(int type, int data) {
         BaseItem dropped = nonDataBlockBagItems.get(type);
         if (dropped != null) return dropped;
@@ -1445,8 +1473,8 @@ public enum BlockType {
      * dropped, 0 will be returned. If the block should not be destroyed
      * (i.e. bedrock), -1 will be returned.
      *
-     * @param id
+     * @param id the type ID of the block
-     * @return
+     * @return the dropped item
      * @deprecated This function ignores the data value.
      */
     @Deprecated
@@ -1458,11 +1486,26 @@ public enum BlockType {
         return dropped.getType();
     }
 
+    /**
+     * Get the block drop for this type given a data value.
+     *
+     * @param data the data value
+     * @return the item stack
+     */
     public BaseItemStack getBlockDrop(short data) {
         return getBlockDrop(id, data);
     }
 
     private static final Random random = new Random();
+
+    /**
+     * Get the block drop for a block.
+     *
+     * @param id the type ID of the block
+     * @param data the data value
+     * @return an item or null
+     */
+    @Nullable
     public static BaseItemStack getBlockDrop(int id, short data) {
         int store;
         switch (id) {
@@ -1765,8 +1808,8 @@ public enum BlockType {
      * Returns the direction to the block(B) this block(A) is attached to.
      * Attached means that if block B is destroyed, block A will pop off.
      *
-     * @param type The block id of block A
+     * @param type the block id of block A
-     * @param data The data value of block A
+     * @param data the data value of block A
      * @return direction to block B
      */
     public static PlayerDirection getAttachment(int type, int data) {

src/main/java/com/sk89q/worldedit/blocks/Blocks.java

@@ -0,0 +1,49 @@
+/*
+ * WorldEdit, a Minecraft world manipulation toolkit
+ * Copyright (C) sk89q <http://www.sk89q.com>
+ * Copyright (C) WorldEdit team and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by the
+ * Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.sk89q.worldedit.blocks;
+
+import java.util.Collection;
+
+/**
+ * Block-related utility methods.
+ */
+public final class Blocks {
+
+    private Blocks() {
+    }
+
+    /**
+     * Checks whether a given block is in a list of base blocks.
+     *
+     * @param collection the collection
+     * @param o the block
+     * @return true if the collection contains the given block
+     */
+    public static boolean containsFuzzy(Collection<? extends BaseBlock> collection, BaseBlock o) {
+        // Allow masked data in the searchBlocks to match various types
+        for (BaseBlock b : collection) {
+            if (b.equalsFuzzy(o)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+}

src/main/java/com/sk89q/worldedit/blocks/ClothColor.java

@@ -19,16 +19,18 @@
 
 package com.sk89q.worldedit.blocks;
 
+import javax.annotation.Nullable;
 import java.util.Map;
 import java.util.HashMap;
 import java.util.EnumSet;
 
 /**
- * Cloth colors.
+ * The colors for wool.
  *
- * @author sk89q
+ * <p>This class may be removed in the future.</p>
  */
 public enum ClothColor {
+
     WHITE(ID.WHITE, "White", "white"),
     ORANGE(ID.ORANGE, "Orange", "orange"),
     MAGENTA(ID.MAGENTA, "Magenta", "magenta"),
@@ -63,6 +65,9 @@ public enum ClothColor {
         public static final int DARK_GREEN = 13;
         public static final int RED = 14;
         public static final int BLACK = 15;
+
+        private ID() {
+        }
     }
 
     /**
@@ -91,8 +96,9 @@ public enum ClothColor {
     /**
      * Construct the type.
      *
-     * @param id
+     * @param id the ID of the color
-     * @param name
+     * @param name the name of the color
+     * @param lookupKey a name to refer to the color by
      */
     ClothColor(int id, String name, String lookupKey) {
         this.id = id;
@@ -103,8 +109,9 @@ public enum ClothColor {
     /**
      * Construct the type.
      *
-     * @param id
+     * @param id the ID of the color
-     * @param name
+     * @param name the name of the color
+     * @param lookupKeys an array of lookup keys
      */
     ClothColor(int id, String name, String[] lookupKeys) {
         this.id = id;
@@ -115,9 +122,10 @@ public enum ClothColor {
     /**
      * Return type from ID. May return null.
      *
-     * @param id
+     * @param id the ID
-     * @return
+     * @return a color or null
      */
+    @Nullable
     public static ClothColor fromID(int id) {
         return ids.get(id);
     }
@@ -125,9 +133,10 @@ public enum ClothColor {
     /**
      * Return type from name. May return null.
      *
-     * @param name
+     * @param name the name of the color
-     * @return
+     * @return a color or null
      */
+    @Nullable
     public static ClothColor lookup(String name) {
         return lookup.get(name.toLowerCase());
     }
@@ -135,7 +144,7 @@ public enum ClothColor {
     /**
      * Get item numeric ID.
      *
-     * @return
+     * @return the ID
      */
     public int getID() {
         return id;
@@ -144,9 +153,10 @@ public enum ClothColor {
     /**
      * Get user-friendly item name.
      *
-     * @return
+     * @return the name
      */
     public String getName() {
         return name;
     }
+
 }

src/main/java/com/sk89q/worldedit/blocks/ItemID.java

@@ -21,10 +21,9 @@ package com.sk89q.worldedit.blocks;
 
 /**
  * List of item IDs.
- *
- * @author sk89q
  */
 public final class ItemID {
+
     public static final int IRON_SHOVEL = 256;
     public static final int IRON_PICK = 257;
     public static final int IRON_AXE = 258;
@@ -202,4 +201,5 @@ public final class ItemID {
 
     private ItemID() {
     }
+
 }

src/main/java/com/sk89q/worldedit/blocks/ItemType.java

@@ -19,6 +19,9 @@
 
 package com.sk89q.worldedit.blocks;
 
+import com.sk89q.util.StringUtil;
+
+import javax.annotation.Nullable;
 import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -26,14 +29,11 @@ import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Set;
 
-import com.sk89q.util.StringUtil;
-
 /**
- * ItemType types.
+ * An enum of types of items.
- *
- * @author sk89q
  */
 public enum ItemType {
+
     // Blocks
     AIR(BlockID.AIR, "Air", "air"),
     STONE(BlockID.STONE, "Stone", "stone", "rock"),
@@ -412,8 +412,9 @@ public enum ItemType {
     /**
      * Construct the type.
      *
-     * @param id
+     * @param id the type ID of the item
-     * @param name
+     * @param name the name of the item
+     * @param lookupKey a name to refer to the item type by
      */
     ItemType(int id, String name, String lookupKey) {
         this.id = id;
@@ -424,8 +425,9 @@ public enum ItemType {
     /**
      * Construct the type.
      *
-     * @param id
+     * @param id the type ID of the item
-     * @param name
+     * @param name the name of the item
+     * @param lookupKeys a list of names to refer to the item type by
      */
     ItemType(int id, String name, String... lookupKeys) {
         this.id = id;
@@ -436,9 +438,10 @@ public enum ItemType {
     /**
      * Return type from ID. May return null.
      *
-     * @param id
+     * @param id the type ID of the item
-     * @return
+     * @return an item type or null
      */
+    @Nullable
     public static ItemType fromID(int id) {
         return ids.get(id);
     }
@@ -446,8 +449,10 @@ public enum ItemType {
     /**
      * Get a name for the item.
      *
-     * @param id
+     * <p>If the item type is not null, the numeric ID will be returned.</p>
-     * @return
+     *
+     * @param id the type ID of the item
+     * @return a name for the item
      */
     public static String toName(int id) {
         ItemType type = ids.get(id);
@@ -461,8 +466,10 @@ public enum ItemType {
     /**
      * Get a name for a held item.
      *
-     * @param id
+     * <p>If the item type is not null, the numeric ID will be returned.</p>
-     * @return
+     *
+     * @param id the type ID of the item
+     * @return the name of the item
      */
     public static String toHeldName(int id) {
         if (id == 0) {
@@ -479,9 +486,10 @@ public enum ItemType {
     /**
      * Return type from name. May return null.
      *
-     * @param name
+     * @param name the name
-     * @return
+     * @return the type or null
      */
+    @Nullable
     public static ItemType lookup(String name) {
         return lookup(name, true);
     }
@@ -489,10 +497,11 @@ public enum ItemType {
     /**
      * Return type from name. May return null.
      *
-     * @param name
+     * @param name the name
-     * @param fuzzy
+     * @param fuzzy true to do a fuzzy string search
-     * @return
+     * @return the type or null
      */
+    @Nullable
     public static ItemType lookup(String name, boolean fuzzy) {
         try {
             return fromID(Integer.parseInt(name));
@@ -504,7 +513,7 @@ public enum ItemType {
     /**
      * Get item numeric ID.
      *
-     * @return
+     * @return the type ID of this item
      */
     public int getID() {
         return id;
@@ -513,7 +522,7 @@ public enum ItemType {
     /**
      * Get user-friendly item name.
      *
-     * @return
+     * @return a name of this item
      */
     public String getName() {
         return name;
@@ -522,7 +531,7 @@ public enum ItemType {
     /**
      * Get a list of aliases.
      *
-     * @return
+     * @return a list of aliases
      */
     public String[] getAliases() {
         return lookupKeys;
@@ -620,8 +629,8 @@ public enum ItemType {
     /**
      * Returns true if an item should not be stacked.
      *
-     * @param id
+     * @param id the type ID of the item
-     * @return
+     * @return true if the item should not stack
      */
     public static boolean shouldNotStack(int id) {
         return shouldNotStack.contains(id);
@@ -668,10 +677,11 @@ public enum ItemType {
      * Returns true if an item uses its damage value for something
      * other than damage.
      *
-     * @param id
+     * @param id the type ID of the item
-     * @return
+     * @return true if the item uses its damage value
      */
     public static boolean usesDamageValue(int id) {
         return usesDamageValue.contains(id);
     }
+
 }

src/main/java/com/sk89q/worldedit/blocks/TileEntityBlock.java

@@ -22,11 +22,10 @@ package com.sk89q.worldedit.blocks;
 import com.sk89q.worldedit.world.NbtValued;
 
 /**
- * Indicates a block that contains extra data identified as an NBT structure. Compared
+ * Indicates a block that contains extra data identified as an NBT structure.
- * to a {@link NbtValued}, tile entity blocks also contain an ID.
+ * Compared to a {@link NbtValued}, tile entity blocks also contain an ID.
  *
  * @see NbtValued
- * @author sk89q
  */
 public interface TileEntityBlock extends NbtValued {
 

src/main/java/com/sk89q/worldedit/function/mask/FuzzyBlockMask.java

@@ -19,9 +19,10 @@
 
 package com.sk89q.worldedit.function.mask;
 
-import com.sk89q.worldedit.extent.Extent;
 import com.sk89q.worldedit.Vector;
 import com.sk89q.worldedit.blocks.BaseBlock;
+import com.sk89q.worldedit.blocks.Blocks;
+import com.sk89q.worldedit.extent.Extent;
 
 import java.util.Collection;
 
@@ -41,6 +42,6 @@ public class FuzzyBlockMask extends BlockMask {
         Collection<BaseBlock> blocks = getBlocks();
         BaseBlock lazyBlock = extent.getLazyBlock(vector);
         BaseBlock compare = new BaseBlock(lazyBlock.getType(), lazyBlock.getData());
-        return BaseBlock.containsFuzzy(blocks, compare);
+        return Blocks.containsFuzzy(blocks, compare);
     }
 }