From d8622fb30f2e5008bdd4611bd14e7e3764d7caa3 Mon Sep 17 00:00:00 2001 From: sk89q Date: Tue, 29 Jul 2014 14:23:00 -0700 Subject: [PATCH] Fix some additional Javadoc errors. --- src/main/java/com/sk89q/jnbt/CompoundTag.java | 2 + src/main/java/com/sk89q/jnbt/ListTag.java | 2 + .../util/commands/CommandPermissions.java | 2 + .../util/commands/CommandsManager.java | 7 ++- .../minecraft/util/commands/Injector.java | 9 ++- .../minecraft/util/commands/Logging.java | 4 +- .../util/commands/NestedCommand.java | 4 ++ .../com/sk89q/util/yaml/YAMLProcessor.java | 3 +- .../com/sk89q/worldedit/CuboidClipboard.java | 1 + .../java/com/sk89q/worldedit/EditSession.java | 58 +++++++++++++------ .../sk89q/worldedit/EditSessionFactory.java | 28 +++++++++ src/main/java/com/sk89q/worldedit/Vector.java | 2 +- .../java/com/sk89q/worldedit/Vector2D.java | 3 +- .../com/sk89q/worldedit/extent/Extent.java | 1 + .../sk89q/worldedit/extent/OutputExtent.java | 1 + 15 files changed, 96 insertions(+), 31 deletions(-) diff --git a/src/main/java/com/sk89q/jnbt/CompoundTag.java b/src/main/java/com/sk89q/jnbt/CompoundTag.java index 6f959e81a..4ab326d5e 100644 --- a/src/main/java/com/sk89q/jnbt/CompoundTag.java +++ b/src/main/java/com/sk89q/jnbt/CompoundTag.java @@ -309,7 +309,9 @@ public final class CompoundTag extends Tag { * list will also be returned.

* * @param key the key + * @param listType the class of the contained type * @return a list of tags + * @param the type of list */ @SuppressWarnings("unchecked") public List getList(String key, Class listType) { diff --git a/src/main/java/com/sk89q/jnbt/ListTag.java b/src/main/java/com/sk89q/jnbt/ListTag.java index b03e35d33..28b004588 100644 --- a/src/main/java/com/sk89q/jnbt/ListTag.java +++ b/src/main/java/com/sk89q/jnbt/ListTag.java @@ -323,7 +323,9 @@ public final class ListTag extends Tag { * list will also be returned.

* * @param index the index + * @param listType the class of the contained type * @return a list of tags + * @param the NBT type */ @SuppressWarnings("unchecked") public List getList(int index, Class listType) { diff --git a/src/main/java/com/sk89q/minecraft/util/commands/CommandPermissions.java b/src/main/java/com/sk89q/minecraft/util/commands/CommandPermissions.java index 6e890b7fb..90fd29709 100644 --- a/src/main/java/com/sk89q/minecraft/util/commands/CommandPermissions.java +++ b/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(); diff --git a/src/main/java/com/sk89q/minecraft/util/commands/CommandsManager.java b/src/main/java/com/sk89q/minecraft/util/commands/CommandsManager.java index 6ee1fd65f..eec7ced7c 100644 --- a/src/main/java/com/sk89q/minecraft/util/commands/CommandsManager.java +++ b/src/main/java/com/sk89q/minecraft/util/commands/CommandsManager.java @@ -396,10 +396,9 @@ public abstract class CommandsManager { * @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 { /** * 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; diff --git a/src/main/java/com/sk89q/minecraft/util/commands/Injector.java b/src/main/java/com/sk89q/minecraft/util/commands/Injector.java index a2528de9b..4978e8eeb 100644 --- a/src/main/java/com/sk89q/minecraft/util/commands/Injector.java +++ b/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; } diff --git a/src/main/java/com/sk89q/minecraft/util/commands/Logging.java b/src/main/java/com/sk89q/minecraft/util/commands/Logging.java index 617a0ee18..dc64b5e16 100644 --- a/src/main/java/com/sk89q/minecraft/util/commands/Logging.java +++ b/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(); diff --git a/src/main/java/com/sk89q/minecraft/util/commands/NestedCommand.java b/src/main/java/com/sk89q/minecraft/util/commands/NestedCommand.java index bb4a77970..ae0e5ae14 100644 --- a/src/main/java/com/sk89q/minecraft/util/commands/NestedCommand.java +++ b/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; diff --git a/src/main/java/com/sk89q/util/yaml/YAMLProcessor.java b/src/main/java/com/sk89q/util/yaml/YAMLProcessor.java index 7e23fc422..e0ecdf33f 100644 --- a/src/main/java/com/sk89q/util/yaml/YAMLProcessor.java +++ b/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) { diff --git a/src/main/java/com/sk89q/worldedit/CuboidClipboard.java b/src/main/java/com/sk89q/worldedit/CuboidClipboard.java index bdb8bab39..17c5149d3 100644 --- a/src/main/java/com/sk89q/worldedit/CuboidClipboard.java +++ b/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) { diff --git a/src/main/java/com/sk89q/worldedit/EditSession.java b/src/main/java/com/sk89q/worldedit/EditSession.java index 903c866cc..19420c31a 100644 --- a/src/main/java/com/sk89q/worldedit/EditSession.java +++ b/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}.

*/ -@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 (>= 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 (>= 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 searchIDs) { Set passOn = new HashSet(); 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 nodevectors, double tension, double bias, double continuity, double quality, double radius, boolean filled) throws MaxChangedBlocksException { diff --git a/src/main/java/com/sk89q/worldedit/EditSessionFactory.java b/src/main/java/com/sk89q/worldedit/EditSessionFactory.java index c1d4ead5c..b5ce151b9 100644 --- a/src/main/java/com/sk89q/worldedit/EditSessionFactory.java +++ b/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 diff --git a/src/main/java/com/sk89q/worldedit/Vector.java b/src/main/java/com/sk89q/worldedit/Vector.java index 6dd084543..e148e75d5 100644 --- a/src/main/java/com/sk89q/worldedit/Vector.java +++ b/src/main/java/com/sk89q/worldedit/Vector.java @@ -599,7 +599,7 @@ public class Vector implements Comparable { /** * Rounds all components to the closest integer. * - *

Components < 0.5 are rounded down, otherwise up.

+ *

Components < 0.5 are rounded down, otherwise up.

* * @return a new vector */ diff --git a/src/main/java/com/sk89q/worldedit/Vector2D.java b/src/main/java/com/sk89q/worldedit/Vector2D.java index cf1f98097..2c295ca2c 100644 --- a/src/main/java/com/sk89q/worldedit/Vector2D.java +++ b/src/main/java/com/sk89q/worldedit/Vector2D.java @@ -509,7 +509,7 @@ public class Vector2D { /** * Rounds all components to the closest integer. * - *

Components < 0.5 are rounded down, otherwise up.

+ *

Components < 0.5 are rounded down, otherwise up.

* * @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) { diff --git a/src/main/java/com/sk89q/worldedit/extent/Extent.java b/src/main/java/com/sk89q/worldedit/extent/Extent.java index 436c59ea8..617dff41f 100644 --- a/src/main/java/com/sk89q/worldedit/extent/Extent.java +++ b/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.

* + * @param region the region in which entities must be contained * @return a list of entities */ List getEntities(Region region); diff --git a/src/main/java/com/sk89q/worldedit/extent/OutputExtent.java b/src/main/java/com/sk89q/worldedit/extent/OutputExtent.java index e7218e719..cdb21d662 100644 --- a/src/main/java/com/sk89q/worldedit/extent/OutputExtent.java +++ b/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;