Fix some additional Javadoc errors.

src/main/java/com/sk89q/jnbt/CompoundTag.java

@@ -309,7 +309,9 @@ public final class CompoundTag extends Tag {
      * list will also be returned.</p>
      *
      * @param key the key
+     * @param listType the class of the contained type
      * @return a list of tags
+     * @param <T> the type of list
      */
     @SuppressWarnings("unchecked")
     public <T extends Tag> List<T> getList(String key, Class<T> listType) {

src/main/java/com/sk89q/jnbt/ListTag.java

@@ -323,7 +323,9 @@ public final class ListTag extends Tag {
      * list will also be returned.</p>
      *
      * @param index the index
+     * @param listType the class of the contained type
      * @return a list of tags
+     * @param <T> the NBT type
      */
     @SuppressWarnings("unchecked")
     public <T extends Tag> List<T> getList(int index, Class<T> listType) {

src/main/java/com/sk89q/minecraft/util/commands/CommandPermissions.java

@@ -31,6 +31,8 @@ public @interface CommandPermissions {
     /**
      * A list of permissions. Only one permission has to be met
      * for the command to be permitted.
+     *
+     * @return a list of permissions strings
      */
     String[] value();
 

src/main/java/com/sk89q/minecraft/util/commands/CommandsManager.java

@@ -396,10 +396,9 @@ public abstract class CommandsManager<T> {
      * @param args arguments
      * @param player command source
      * @param methodArgs method arguments
-     * @throws CommandException
+     * @throws CommandException thrown when the command throws an error
      */
-    public void execute(String cmd, String[] args, T player,
-            Object... methodArgs) throws CommandException {
+    public void execute(String cmd, String[] args, T player, Object... methodArgs) throws CommandException {
 
         String[] newArgs = new String[args.length + 1];
         System.arraycopy(args, 0, newArgs, 1, args.length);
@@ -574,6 +573,8 @@ public abstract class CommandsManager<T> {
     /**
      * Get the injector used to create new instances. This can be
      * null, in which case only classes will be registered statically.
+     *
+     * @return an injector instance
      */
     public Injector getInjector() {
         return injector;

src/main/java/com/sk89q/minecraft/util/commands/Injector.java

@@ -31,11 +31,10 @@ public interface Injector {
      * 
      * @param cls class
      * @return object
-     * @throws IllegalAccessException
-     * @throws InstantiationException
-     * @throws InvocationTargetException
+     * @throws IllegalAccessException thrown on injection fault
+     * @throws InstantiationException thrown on injection fault
+     * @throws InvocationTargetException thrown on injection fault
      */
-    public Object getInstance(Class<?> cls) throws InvocationTargetException,
-            IllegalAccessException, InstantiationException;
+    public Object getInstance(Class<?> cls) throws InvocationTargetException, IllegalAccessException, InstantiationException;
 
 }

src/main/java/com/sk89q/minecraft/util/commands/Logging.java

@@ -59,7 +59,9 @@ public @interface Logging {
     }
 
     /**
-     * Log mode. Can be either POSITION, REGION, ORIENTATION_REGION, PLACEMENT or ALL.
+     * Log mode.
+     *
+     * @return either POSITION, REGION, ORIENTATION_REGION, PLACEMENT or ALL
      */
     LogMode value();
 

src/main/java/com/sk89q/minecraft/util/commands/NestedCommand.java

@@ -35,11 +35,15 @@ public @interface NestedCommand {
 
     /**
      * A list of classes with the child commands.
+     *
+     * @return a list of classes
      */
     Class<?>[] value();
 
     /**
      * If set to true it will execute the body of the tagged method.
+     *
+     * @return true to execute the body of the annotated method
      */
     boolean executeBody() default false;
 

src/main/java/com/sk89q/util/yaml/YAMLProcessor.java

@@ -100,7 +100,7 @@ public class YAMLProcessor extends YAMLNode {
     /**
      * Loads the configuration file.
      *
-     * @throws java.io.IOException
+     * @throws java.io.IOException on load error
      */
     public void load() throws IOException {
         InputStream stream = null;
@@ -298,6 +298,7 @@ public class YAMLProcessor extends YAMLNode {
      * This method returns an empty ConfigurationNode for using as a
      * default in methods that select a node from a node list.
      *
+     * @param writeDefaults true to write default values when a property is requested that doesn't exist
      * @return a node
      */
     public static YAMLNode getEmptyNode(boolean writeDefaults) {

src/main/java/com/sk89q/worldedit/CuboidClipboard.java

@@ -505,6 +505,7 @@ public class CuboidClipboard {
      * Set the block at a position in the clipboard.
      *
      * @param position the point, relative to the origin of the copy (0, 0, 0) and not to the actual copy origin.
+     * @param block the block to set
      * @throws ArrayIndexOutOfBoundsException if the position is outside the bounds of the CuboidClipboard
      */
     public void setBlock(Vector position, BaseBlock block) {

src/main/java/com/sk89q/worldedit/EditSession.java

@@ -95,7 +95,7 @@ import static com.sk89q.worldedit.regions.Regions.*;
  * {@link Extent}s that are chained together. For example, history is logged
  * using the {@link ChangeSetExtent}.</p>
  */
-@SuppressWarnings("FieldCanBeLocal")
+@SuppressWarnings({"FieldCanBeLocal", "deprecation"})
 public class EditSession implements Extent {
 
     private static final Logger log = Logger.getLogger(EditSession.class.getCanonicalName());
@@ -134,6 +134,10 @@ public class EditSession implements Extent {
     private Mask oldMask;
 
     /**
+     * Create a new instance.
+     *
+     * @param world a world
+     * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
      * @deprecated use {@link WorldEdit#getEditSessionFactory()} to create {@link EditSession}s
      */
     @SuppressWarnings("deprecation")
@@ -143,6 +147,11 @@ public class EditSession implements Extent {
     }
 
     /**
+     * Create a new instance.
+     *
+     * @param world a world
+     * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
+     * @param blockBag the block bag to set, or null to use none
      * @deprecated use {@link WorldEdit#getEditSessionFactory()} to create {@link EditSession}s
      */
     @Deprecated
@@ -234,7 +243,7 @@ public class EditSession implements Extent {
      * Get the maximum number of blocks that can be changed. -1 will be returned
      * if it the limit disabled.
      *
-     * @return the limit (>= 0) or -1 for no limit
+     * @return the limit (&gt;= 0) or -1 for no limit
      */
     public int getBlockChangeLimit() {
         return changeLimiter.getLimit();
@@ -243,7 +252,7 @@ public class EditSession implements Extent {
     /**
      * Set the maximum number of blocks that can be changed.
      *
-     * @param limit the limit (>= 0) or -1 for no limit
+     * @param limit the limit (&gt;= 0) or -1 for no limit
      */
     public void setBlockChangeLimit(int limit) {
         changeLimiter.setLimit(limit);
@@ -299,6 +308,9 @@ public class EditSession implements Extent {
     }
 
     /**
+     * Set the mask.
+     *
+     * @param mask the mask
      * @deprecated Use {@link #setMask(Mask)}
      */
     @Deprecated
@@ -483,6 +495,7 @@ public class EditSession implements Extent {
      * @param block the block
      * @param stage the level
      * @return whether the block changed
+     * @throws WorldEditException thrown on a set error
      */
     public boolean setBlock(Vector position, BaseBlock block, Stage stage) throws WorldEditException {
         switch (stage) {
@@ -683,6 +696,13 @@ public class EditSession implements Extent {
         return bypassNone.commit();
     }
 
+    /**
+     * Count the number of blocks of a given list of types in a region.
+     *
+     * @param region the region
+     * @param searchIDs a list of IDs to search
+     * @return the number of found blocks
+     */
     public int countBlock(Region region, Set<Integer> searchIDs) {
         Set<BaseBlock> passOn = new HashSet<BaseBlock>();
         for (Integer i : searchIDs) {
@@ -954,7 +974,7 @@ public class EditSession implements Extent {
      * @param region the region
      * @param block the block to place
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     @SuppressWarnings("deprecation")
     public int makeCuboidFaces(Region region, BaseBlock block) throws MaxChangedBlocksException {
@@ -1009,7 +1029,7 @@ public class EditSession implements Extent {
      * @param region the region
      * @param block the block to place
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     @SuppressWarnings("deprecation")
     public int makeCuboidWalls(Region region, BaseBlock block) throws MaxChangedBlocksException {
@@ -1301,7 +1321,7 @@ public class EditSession implements Extent {
      * @param height The cylinder's up/down extent. If negative, extend downward.
      * @param filled If false, only a shell will be generated.
      * @return number of blocks changed
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int makeCylinder(Vector pos, Pattern block, double radius, int height, boolean filled) throws MaxChangedBlocksException {
         return makeCylinder(pos, block, radius, radius, height, filled);
@@ -1317,7 +1337,7 @@ public class EditSession implements Extent {
      * @param height The cylinder's up/down extent. If negative, extend downward.
      * @param filled If false, only a shell will be generated.
      * @return number of blocks changed
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int makeCylinder(Vector pos, Pattern block, double radiusX, double radiusZ, int height, boolean filled) throws MaxChangedBlocksException {
         int affected = 0;
@@ -1395,7 +1415,7 @@ public class EditSession implements Extent {
     * @param radius The sphere's radius
     * @param filled If false, only a shell will be generated.
     * @return number of blocks changed
-    * @throws MaxChangedBlocksException
+    * @throws MaxChangedBlocksException thrown if too many blocks are changed
     */
     public int makeSphere(Vector pos, Pattern block, double radius, boolean filled) throws MaxChangedBlocksException {
         return makeSphere(pos, block, radius, radius, radius, filled);
@@ -1411,7 +1431,7 @@ public class EditSession implements Extent {
      * @param radiusZ The sphere/ellipsoid's largest east/west extent
      * @param filled If false, only a shell will be generated.
      * @return number of blocks changed
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int makeSphere(Vector pos, Pattern block, double radiusX, double radiusY, double radiusZ, boolean filled) throws MaxChangedBlocksException {
         int affected = 0;
@@ -1497,7 +1517,7 @@ public class EditSession implements Extent {
      * @param size size of pyramid
      * @param filled true if filled
      * @return number of blocks changed
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int makePyramid(Vector position, Pattern block, int size, boolean filled) throws MaxChangedBlocksException {
         int affected = 0;
@@ -1537,7 +1557,7 @@ public class EditSession implements Extent {
      * @param position the position
      * @param radius the radius
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int thaw(Vector position, double radius)
             throws MaxChangedBlocksException {
@@ -1596,7 +1616,7 @@ public class EditSession implements Extent {
      * @param position a position
      * @param radius a radius
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int simulateSnow(Vector position, double radius) throws MaxChangedBlocksException {
         int affected = 0;
@@ -1660,7 +1680,7 @@ public class EditSession implements Extent {
      * @param position a position
      * @param radius a radius
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      * @deprecated Use {@link #green(Vector, double, boolean)}.
      */
     @Deprecated
@@ -1675,7 +1695,7 @@ public class EditSession implements Extent {
      * @param radius a radius
      * @param onlyNormalDirt only affect normal dirt (data value 0)
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int green(Vector position, double radius, boolean onlyNormalDirt)
             throws MaxChangedBlocksException {
@@ -1737,7 +1757,7 @@ public class EditSession implements Extent {
      * @param position the base position
      * @param apothem the apothem of the (square) area
      * @return number of patches created
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int makePumpkinPatches(Vector position, int apothem) throws MaxChangedBlocksException {
         // We want to generate pumpkins
@@ -1766,7 +1786,7 @@ public class EditSession implements Extent {
      * @param density between 0 and 1, inclusive
      * @param treeGenerator the tree genreator
      * @return number of trees created
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int makeForest(Vector basePosition, int size, double density, TreeGenerator treeGenerator) throws MaxChangedBlocksException {
         int affected = 0;
@@ -2005,7 +2025,7 @@ public class EditSession implements Extent {
      * @param pattern The block pattern to use
      *
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int hollowOutRegion(Region region, int thickness, Pattern pattern) throws MaxChangedBlocksException {
         int affected = 0;
@@ -2086,7 +2106,7 @@ public class EditSession implements Extent {
      * @param filled If false, only a shell will be generated.
      *
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int drawLine(Pattern pattern, Vector pos1, Vector pos2, double radius, boolean filled)
             throws MaxChangedBlocksException {
@@ -2157,7 +2177,7 @@ public class EditSession implements Extent {
      * @param filled If false, only a shell will be generated.
      *
      * @return number of blocks affected
-     * @throws MaxChangedBlocksException
+     * @throws MaxChangedBlocksException thrown if too many blocks are changed
      */
     public int drawSpline(Pattern pattern, List<Vector> nodevectors, double tension, double bias, double continuity, double quality, double radius, boolean filled)
             throws MaxChangedBlocksException {

src/main/java/com/sk89q/worldedit/EditSessionFactory.java

@@ -42,6 +42,7 @@ public class EditSessionFactory {
      *
      * @param world the world
      * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
+     * @return an instance
      */
     public EditSession getEditSession(World world, int maxBlocks) {
 
@@ -65,6 +66,7 @@ public class EditSessionFactory {
      * @param world the world
      * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
      * @param player the player that the {@link EditSession} is for
+     * @return an instance
      */
     public EditSession getEditSession(World world, int maxBlocks, Player player) {
 
@@ -88,6 +90,7 @@ public class EditSessionFactory {
      * @param world the world
      * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
      * @param blockBag an optional {@link BlockBag} to use, otherwise null
+     * @return an instance
      */
     public EditSession getEditSession(World world, int maxBlocks, BlockBag blockBag) {
 
@@ -112,6 +115,7 @@ public class EditSessionFactory {
      * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
      * @param blockBag an optional {@link BlockBag} to use, otherwise null
      * @param player the player that the {@link EditSession} is for
+     * @return an instance
      */
     public EditSession getEditSession(World world, int maxBlocks, BlockBag blockBag, Player player) {
 
@@ -134,6 +138,11 @@ public class EditSessionFactory {
     // ------------------------------------------------------------------------
 
     /**
+     * Construct an edit session.
+     *
+     * @param world the world
+     * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
+     * @return an instance
      * @deprecated We are replacing {@link LocalWorld} with {@link World}, so use {@link #getEditSession(World, int)} instead
      */
     @Deprecated
@@ -142,6 +151,12 @@ public class EditSessionFactory {
     }
 
     /**
+     * Construct an edit session.
+     *
+     * @param world the world
+     * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
+     * @param player the player that the {@link EditSession} is for
+     * @return an instance
      * @deprecated We are replacing {@link LocalWorld} with {@link World}, so use {@link #getEditSession(World, int, Player)} instead
      */
     @Deprecated
@@ -150,6 +165,12 @@ public class EditSessionFactory {
     }
 
     /**
+     * Construct an edit session.
+     *
+     * @param world the world
+     * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
+     * @param blockBag an optional {@link BlockBag} to use, otherwise null
+     * @return an instance
      * @deprecated We are replacing {@link LocalWorld} with {@link World}, so use {@link #getEditSession(World, int, BlockBag)} instead
      */
     @Deprecated
@@ -158,6 +179,13 @@ public class EditSessionFactory {
     }
 
     /**
+     * Construct an edit session.
+     *
+     * @param world the world
+     * @param maxBlocks the maximum number of blocks that can be changed, or -1 to use no limit
+     * @param blockBag an optional {@link BlockBag} to use, otherwise null
+     * @param player the player that the {@link EditSession} is for
+     * @return an instance
      * @deprecated We are replacing {@link LocalWorld} with {@link World}, so use {@link #getEditSession(World, int, BlockBag, Player)} instead
      */
     @Deprecated

src/main/java/com/sk89q/worldedit/Vector.java

@@ -599,7 +599,7 @@ public class Vector implements Comparable<Vector> {
     /**
      * Rounds all components to the closest integer.
      *
-     * <p>Components < 0.5 are rounded down, otherwise up.</p>
+     * <p>Components &lt; 0.5 are rounded down, otherwise up.</p>
      *
      * @return a new vector
      */

src/main/java/com/sk89q/worldedit/Vector2D.java

@@ -509,7 +509,7 @@ public class Vector2D {
     /**
      * Rounds all components to the closest integer.
      *
-     * <p>Components < 0.5 are rounded down, otherwise up.</p>
+     * <p>Components &lt; 0.5 are rounded down, otherwise up.</p>
      *
      * @return a new vector
      */
@@ -607,6 +607,7 @@ public class Vector2D {
     /**
      * Creates a 3D vector by adding the specified Y component to this vector.
      *
+     * @param y the Y component
      * @return a new vector
      */
     public Vector toVector(double y) {

src/main/java/com/sk89q/worldedit/extent/Extent.java

@@ -64,6 +64,7 @@ public interface Extent extends InputExtent, OutputExtent {
      * game will not have every chunk loaded), then this list may not be
      * incomplete.</p>
      *
+     * @param region the region in which entities must be contained
      * @return a list of entities
      */
     List<? extends Entity> getEntities(Region region);

src/main/java/com/sk89q/worldedit/extent/OutputExtent.java

@@ -48,6 +48,7 @@ public interface OutputExtent {
      * @param position position of the block
      * @param block block to set
      * @return true if the block was successfully set (return value may not be accurate)
+     * @throws WorldEditException thrown on an error
      */
     boolean setBlock(Vector position, BaseBlock block) throws WorldEditException;