General code cleanup.

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

@@ -27,10 +27,10 @@ import com.sk89q.worldedit.expression.Expression;
 import com.sk89q.worldedit.expression.ExpressionException;
 import com.sk89q.worldedit.expression.runtime.RValue;
 import com.sk89q.worldedit.extent.*;
-import com.sk89q.worldedit.extent.reorder.SimpleBlockReorder;
+import com.sk89q.worldedit.extent.reorder.MultiStageReorder;
 import com.sk89q.worldedit.function.GroundFunction;
 import com.sk89q.worldedit.function.RegionMaskingFilter;
-import com.sk89q.worldedit.function.block.BlockCount;
+import com.sk89q.worldedit.function.block.Counter;
 import com.sk89q.worldedit.function.block.BlockReplace;
 import com.sk89q.worldedit.function.block.Naturalizer;
 import com.sk89q.worldedit.function.generator.GardenPatchGenerator;
@@ -93,7 +93,7 @@ public class EditSession implements Extent {
 
     private final FastModeExtent fastModeExtent;
     private final BlockBagExtent blockBagExtent;
-    private final SimpleBlockReorder reorderExtent;
+    private final MultiStageReorder reorderExtent;
     private final MaskingExtent maskingExtent;
     private final BlockChangeLimiter changeLimiter;
 
@@ -136,7 +136,7 @@ public class EditSession implements Extent {
         blockBagExtent                          = new BlockBagExtent(validator, world, blockBag);
 
         // This extent can be skipped by calling rawSetBlock()
-        reorderExtent                           = new SimpleBlockReorder(blockBagExtent, false);
+        reorderExtent                           = new MultiStageReorder(blockBagExtent, false);
 
         // These extents can be skipped by calling smartSetBlock()
         ChangeSetExtent changeSetExtent         = new ChangeSetExtent(reorderExtent, changeSet);
@@ -581,7 +581,7 @@ public class EditSession implements Extent {
      */
     public int countBlocks(Region region, Set<BaseBlock> searchBlocks) {
         FuzzyBlockMask mask = new FuzzyBlockMask(this, searchBlocks);
-        BlockCount count = new BlockCount();
+        Counter count = new Counter();
         RegionMaskingFilter filter = new RegionMaskingFilter(mask, count);
         RegionVisitor visitor = new RegionVisitor(region, filter);
         OperationHelper.completeBlindly(visitor); // We can't throw exceptions, nor do we expect any
@@ -983,7 +983,7 @@ public class EditSession implements Extent {
 
         BlockReplace replace = new BlockReplace(this, Patterns.wrap(pattern));
         RegionOffset offset = new RegionOffset(new Vector(0, 1, 0), replace);
-        GroundFunction ground = new GroundFunction(this, offset);
+        GroundFunction ground = new GroundFunction(new ExistingBlockMask(this), offset);
         LayerVisitor visitor = new LayerVisitor(asFlatRegion(region), minimumBlockY(region), maximumBlockY(region), ground);
         OperationHelper.completeLegacy(visitor);
         return ground.getAffected();
@@ -1634,7 +1634,7 @@ public class EditSession implements Extent {
                 position.add(apothem, 10, apothem));
         double density = 0.02;
 
-        GroundFunction ground = new GroundFunction(this, generator);
+        GroundFunction ground = new GroundFunction(new ExistingBlockMask(this), generator);
         LayerVisitor visitor = new LayerVisitor(region, minimumBlockY(region), maximumBlockY(region), ground);
         visitor.setMask(new NoiseFilter2D(new RandomNoise(), density));
         OperationHelper.completeLegacy(visitor);

src/main/java/com/sk89q/worldedit/commands/RegionCommands.java

@@ -27,6 +27,7 @@ import com.sk89q.worldedit.*;
 import com.sk89q.worldedit.blocks.BaseBlock;
 import com.sk89q.worldedit.blocks.BlockID;
 import com.sk89q.worldedit.expression.ExpressionException;
+import com.sk89q.worldedit.function.mask.ExistingBlockMask;
 import com.sk89q.worldedit.math.convolution.GaussianKernel;
 import com.sk89q.worldedit.math.convolution.HeightMap;
 import com.sk89q.worldedit.math.convolution.HeightMapFilter;
@@ -551,7 +552,7 @@ public class RegionCommands {
         Region region = session.getSelection(player.getWorld());
 
         ForestGenerator generator = new ForestGenerator(editSession, new TreeGenerator(type));
-        GroundFunction ground = new GroundFunction(editSession, generator);
+        GroundFunction ground = new GroundFunction(new ExistingBlockMask(editSession), generator);
         LayerVisitor visitor = new LayerVisitor(asFlatRegion(region), minimumBlockY(region), maximumBlockY(region), ground);
         visitor.setMask(new NoiseFilter2D(new RandomNoise(), density));
         OperationHelper.completeLegacy(visitor);
@@ -573,7 +574,7 @@ public class RegionCommands {
 
         Region region = session.getSelection(player.getWorld());
         FloraGenerator generator = new FloraGenerator(editSession);
-        GroundFunction ground = new GroundFunction(editSession, generator);
+        GroundFunction ground = new GroundFunction(new ExistingBlockMask(editSession), generator);
         LayerVisitor visitor = new LayerVisitor(asFlatRegion(region), minimumBlockY(region), maximumBlockY(region), ground);
         visitor.setMask(new NoiseFilter2D(new RandomNoise(), density));
         OperationHelper.completeLegacy(visitor);

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

@@ -26,6 +26,9 @@ import com.sk89q.worldedit.function.mask.Mask;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * Requires that all mutating methods pass a given {@link Mask}.
+ */
 public class MaskingExtent extends ExtentDelegate {
 
     private Mask mask;
@@ -63,11 +66,7 @@ public class MaskingExtent extends ExtentDelegate {
 
     @Override
     public boolean setBlock(Vector location, BaseBlock block) throws WorldEditException {
-        if (mask.test(location)) {
-            return super.setBlock(location, block);
-        } else {
-            return false;
-        }
+        return mask.test(location) && super.setBlock(location, block);
     }
 
 }

src/main/java/com/sk89q/worldedit/extent/reorder/MultiStageReorder.java

@@ -39,7 +39,7 @@ import java.util.*;
 /**
  * Re-orders blocks into several stages.
  */
-public class SimpleBlockReorder extends ExtentDelegate {
+public class MultiStageReorder extends ExtentDelegate implements ReorderingExtent {
 
     private TupleArrayList<BlockVector, BaseBlock> stage1 = new TupleArrayList<BlockVector, BaseBlock>();
     private TupleArrayList<BlockVector, BaseBlock> stage2 = new TupleArrayList<BlockVector, BaseBlock>();
@@ -52,7 +52,7 @@ public class SimpleBlockReorder extends ExtentDelegate {
      * @param extent the extent
      * @param enabled true to enable
      */
-    public SimpleBlockReorder(Extent extent, boolean enabled) {
+    public MultiStageReorder(Extent extent, boolean enabled) {
         super(extent);
         this.enabled = enabled;
     }
@@ -62,7 +62,7 @@ public class SimpleBlockReorder extends ExtentDelegate {
      *
      * @param extent the extent
      */
-    public SimpleBlockReorder(Extent extent) {
+    public MultiStageReorder(Extent extent) {
         this(extent, true);
     }
 

src/main/java/com/sk89q/worldedit/extent/reorder/ReorderingExtent.java

@@ -0,0 +1,34 @@
+/*
+ * 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 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.sk89q.worldedit.extent.reorder;
+
+import com.sk89q.worldedit.extent.Extent;
+
+/**
+ * An interface for {@link Extent}s that are meant to reorder changes so
+ * that they are more successful.
+ * </p>
+ * For example, torches in Minecraft need to be placed on a block. A smart
+ * reordering implementation might place the torch after the block has
+ * been placed.
+ */
+public interface ReorderingExtent extends Extent {
+
+}

src/main/java/com/sk89q/worldedit/function/FlatRegionFunction.java

@@ -21,19 +21,21 @@ package com.sk89q.worldedit.function;
 
 import com.sk89q.worldedit.Vector2D;
 import com.sk89q.worldedit.WorldEditException;
+import com.sk89q.worldedit.regions.FlatRegion;
 
 /**
- * Performs a function on points in a flat region.
+ * Performs a function on the columns in a {@link FlatRegion}, or also
+ * known as vectors with only X and Z components (where Y is height).
  */
 public interface FlatRegionFunction {
 
     /**
-     * Apply the function to the given point.
+     * Apply the function to the given position.
      *
-     * @param pt the point
+     * @param position the position
      * @return true if something was changed
      * @throws WorldEditException thrown on an error
      */
-    public boolean apply(Vector2D pt) throws WorldEditException;
+    public boolean apply(Vector2D position) throws WorldEditException;
 
 }

src/main/java/com/sk89q/worldedit/function/GroundFunction.java

@@ -19,11 +19,9 @@
 
 package com.sk89q.worldedit.function;
 
-import com.sk89q.worldedit.EditSession;
 import com.sk89q.worldedit.Vector;
 import com.sk89q.worldedit.WorldEditException;
-import com.sk89q.worldedit.masks.ExistingBlockMask;
-import com.sk89q.worldedit.masks.Mask;
+import com.sk89q.worldedit.function.mask.Mask;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
@@ -32,21 +30,20 @@ import static com.google.common.base.Preconditions.checkNotNull;
  */
 public class GroundFunction implements LayerFunction {
 
-    private final EditSession editSession;
+    private Mask mask;
     private final RegionFunction function;
-    private Mask mask = new ExistingBlockMask();
     private int affected;
 
     /**
      * Create a new ground function.
      *
-     * @param editSession an edit session
+     * @param mask a mask
      * @param function the function to apply
      */
-    public GroundFunction(EditSession editSession, RegionFunction function) {
-        checkNotNull(editSession);
+    public GroundFunction(Mask mask, RegionFunction function) {
+        checkNotNull(mask);
         checkNotNull(function);
-        this.editSession = editSession;
+        this.mask = mask;
         this.function = function;
     }
 
@@ -80,7 +77,7 @@ public class GroundFunction implements LayerFunction {
 
     @Override
     public boolean isGround(Vector position) {
-        return mask.matches(editSession, position);
+        return mask.test(position);
     }
 
     @Override

src/main/java/com/sk89q/worldedit/function/LayerFunction.java

@@ -21,9 +21,10 @@ package com.sk89q.worldedit.function;
 
 import com.sk89q.worldedit.Vector;
 import com.sk89q.worldedit.WorldEditException;
+import com.sk89q.worldedit.function.visitor.LayerVisitor;
 
 /**
- * A function that accepts layers of blocks.
+ * A function that takes a position and a depth.
  */
 public interface LayerFunction {
 
@@ -38,11 +39,14 @@ public interface LayerFunction {
 
     /**
      * Apply the function to the given position.
+     * </p>
+     * The depth would be the number of blocks from the surface if
+     * a {@link LayerVisitor} was used.
      *
      * @param position the position
      * @param depth the depth as a number starting from 0
      * @return true whether this method should be called for further layers
-     * @throws com.sk89q.worldedit.WorldEditException thrown on an error
+     * @throws WorldEditException thrown on an error
      */
     boolean apply(Vector position, int depth) throws WorldEditException;
 }

src/main/java/com/sk89q/worldedit/function/block/BlockReplace.java

@@ -28,7 +28,7 @@ import com.sk89q.worldedit.function.pattern.Pattern;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
- * Replaces blocks with the given pattern.
+ * Replaces blocks with a given pattern.
  */
 public class BlockReplace implements RegionFunction {
 

src/main/java/com/sk89q/worldedit/function/block/Counter.java

@@ -24,9 +24,9 @@ import com.sk89q.worldedit.WorldEditException;
 import com.sk89q.worldedit.function.RegionFunction;
 
 /**
- * Counts the number of blocks.
+ * Keeps a count of the number of times that {@link #apply(Vector)} is called.
  */
- public class BlockCount implements RegionFunction {
+ public class Counter implements RegionFunction {
 
     private int count;
     

src/main/java/com/sk89q/worldedit/function/generator/GardenPatchGenerator.java

@@ -32,6 +32,9 @@ import com.sk89q.worldedit.function.pattern.RandomPattern;
 
 import java.util.Random;
 
+/**
+ * Generates patches of fruit (i.e. pumpkin patches).
+ */
 public class GardenPatchGenerator implements RegionFunction {
 
     private final Random random = new Random();

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

@@ -31,8 +31,8 @@ import java.util.Set;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
- * A mask that checks whether blocks at the given positions are listed
- * in a list of block types.
+ * A mask that checks whether blocks at the given positions are matched by
+ * a block in a list.
  * </p>
  * This mask checks for both an exact block ID and data value match, as well
  * for a block with the same ID but a data value of -1.

src/main/java/com/sk89q/worldedit/function/operation/BlockMapEntryPlacer.java

@@ -29,11 +29,21 @@ import java.util.Map;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * Sets block from an iterator of {@link Map.Entry} containing a
+ * {@link BlockVector} as the key and a {@link BaseBlock} as the value.
+ */
 public class BlockMapEntryPlacer implements Operation {
 
     private final Extent extent;
     private final Iterator<Map.Entry<BlockVector, BaseBlock>> iterator;
 
+    /**
+     * Create a new instance.
+     *
+     * @param extent the extent to set the blocks on
+     * @param iterator the iterator
+     */
     public BlockMapEntryPlacer(Extent extent, Iterator<Map.Entry<BlockVector, BaseBlock>> iterator) {
         checkNotNull(extent);
         checkNotNull(iterator);

src/main/java/com/sk89q/worldedit/math/noise/NoiseGenerator.java

@@ -28,7 +28,8 @@ import com.sk89q.worldedit.Vector2D;
 public interface NoiseGenerator {
 
     /**
-     * Get the noise for the given position.
+     * Get the noise value for the given position. The returned value may
+     * change on every future call for the same position.
      *
      * @param position the position
      * @return a noise value between 0 (inclusive) and 1 (inclusive)
@@ -36,7 +37,8 @@ public interface NoiseGenerator {
     float noise(Vector2D position);
 
     /**
-     * Get the noise for the given position.
+     * Get the noise value for the given position. The returned value may
+     * change on every future call for the same position.
      *
      * @param position the position
      * @return a noise value between 0 (inclusive) and 1 (inclusive)

src/main/java/com/sk89q/worldedit/math/noise/RandomNoise.java

@@ -25,7 +25,8 @@ import com.sk89q.worldedit.Vector2D;
 import java.util.Random;
 
 /**
- * Generates noise non-deterministically using {@link java.util.Random}.
+ * Generates noise using {@link java.util.Random}. Every time a noise
+ * generating function is called, a new value will be returned.
  */
 public class RandomNoise implements NoiseGenerator {
 

src/main/java/com/sk89q/worldedit/math/transform/AffineTransform.java

@@ -24,8 +24,9 @@ import com.sk89q.worldedit.Vector;
 /**
  * An affine transform.
  * </p>
- * This class is from the <a href="http://geom-java.sourceforge.net/index.html>JavaGeom
- * project</a>, which is licensed under LGPL v2.1.
+ * This class is from the
+ * <a href="http://geom-java.sourceforge.net/index.html>JavaGeom project</a>,
+ * which is licensed under LGPL v2.1.
  */
 public class AffineTransform implements Transform {