some code documentation.

PlotSquared/src/com/intellectualcrafters/plot/Configuration.java

@@ -5,6 +5,7 @@ import java.util.List;
 
 import org.bukkit.block.Biome;
 
+
 public class Configuration {
     public static final SettingValue STRING = new SettingValue("STRING") {
         @Override
@@ -179,6 +180,11 @@ public class Configuration {
         }
     };
 
+    /**
+     * 
+     * Create your own SettingValue object to make the management of plotworld configuration easier
+     *
+     */
     public static abstract class SettingValue {
         private String type;
 

PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotManager.java

@@ -25,14 +25,33 @@ import com.intellectualcrafters.plot.PlotWorld;
 
 public class DefaultPlotManager extends PlotManager {
 
+    /*
+     * Default implementation of getting a plot at a given location
+     * 
+     * For a simplified explanation of the math involved:
+     *  - Get the current coords
+     *  - shift these numbers down to something relatable for a single plot 
+     *  (similar to reducing trigonometric functions down to the first quadrant)
+     *  - e.g. If the plot size is 20 blocks, and we are at x=25, it's equivalent to x=5 for that specific plot
+     *  
+     *  From this, and knowing how thick the road is, we can say whether x=5 is road, or plot.
+     *  The number of shifts done, is also counted, and this number gives us the PlotId
+     *  
+     * 
+     */
     @Override
     public PlotId getPlotIdAbs(PlotWorld plotworld, Location loc) {
         DefaultPlotWorld dpw = ((DefaultPlotWorld) plotworld);
 
+        // get x,z loc
         int x = loc.getBlockX();
         int z = loc.getBlockZ();
 
+        // get plot size
         int size = dpw.PLOT_WIDTH + dpw.ROAD_WIDTH;
+        
+        // get size of path on bottom part, and top part of plot
+        // (As 0,0 is in the middle of a road, not the very start)
         int pathWidthLower;
         if ((dpw.ROAD_WIDTH % 2) == 0) {
             pathWidthLower = (int) (Math.floor(dpw.ROAD_WIDTH / 2) - 1);
@@ -40,9 +59,9 @@ public class DefaultPlotManager extends PlotManager {
             pathWidthLower = (int) Math.floor(dpw.ROAD_WIDTH / 2);
         }
 
+        // calulating how many shifts need to be done
         int dx = x / size;
         int dz = z / size;
-
         if (x < 0) {
             dx--;
             x += ((-dx) * size);
@@ -52,19 +71,26 @@ public class DefaultPlotManager extends PlotManager {
             z += ((-dz) * size);
         }
 
+        // reducing to first plot
         int rx = (x) % size;
         int rz = (z) % size;
 
+        // checking if road (return null if so)
         int end = pathWidthLower + dpw.PLOT_WIDTH;
         boolean northSouth = (rz <= pathWidthLower) || (rz > end);
         boolean eastWest = (rx <= pathWidthLower) || (rx > end);
-
         if (northSouth || eastWest) {
             return null;
         }
+        
+        // returning the plot id (based on the number of shifts required)
         return new PlotId(dx + 1, dz + 1);
     }
 
+    /*
+     *  Check if a location is inside a specific plot(non-Javadoc)
+     *   - For this implementation, we don't need to do anything fancier than referring to getPlotIdAbs(...)
+     */
     @Override
     public boolean isInPlotAbs(PlotWorld plotworld, Location loc, Plot plot) {
         PlotId result = getPlotIdAbs(plotworld, loc);
@@ -74,6 +100,10 @@ public class DefaultPlotManager extends PlotManager {
         return result==plot.id;
     }
 
+    /*
+     * Get the bottom plot loc
+     * (some basic math)
+     */
     @Override
     public Location getPlotBottomLocAbs(PlotWorld plotworld, Plot plot) {
         DefaultPlotWorld dpw = ((DefaultPlotWorld) plotworld);
@@ -86,7 +116,11 @@ public class DefaultPlotManager extends PlotManager {
 
         return new Location(Bukkit.getWorld(plot.world), x, 1, z);
     }
-
+    
+    /*
+     * Get the top plot loc
+     * (some basic math)
+     */
     @Override
     public Location getPlotTopLocAbs(PlotWorld plotworld, Plot plot) {
         DefaultPlotWorld dpw = ((DefaultPlotWorld) plotworld);
@@ -100,6 +134,14 @@ public class DefaultPlotManager extends PlotManager {
         return new Location(Bukkit.getWorld(plot.world), x, 256, z);
     }
 
+    /*
+     * Clearing the plot needs to only consider removing the blocks
+     *  - This implementation has used the SetCuboid function, as it is fast, and uses NMS code
+     *  - It also makes use of the fact that deleting chunks is a lot faster than block updates
+     * 
+     * This code is very messy, but you don't need to do something quite as complex unless you happen to have 512x512 sized plots
+     * 
+     */
     @Override
     public boolean clearPlot(Player player, Plot plot, boolean mega) {
         World world = player.getWorld();
@@ -225,6 +267,9 @@ public class DefaultPlotManager extends PlotManager {
         return true;
     }
 
+    /*
+     * Remove sign for a plot 
+     */
     @Override
     public boolean clearSign(Player player, Plot plot, boolean mega) {
         World world = player.getWorld();
@@ -235,6 +280,9 @@ public class DefaultPlotManager extends PlotManager {
         return true;
     }
 
+    /*
+     * Remove any entities, and teleport players inside a plot being cleared
+     */
     @Override
     public boolean clearEntities(Player player, Plot plot, boolean mega) {
         World world = Bukkit.getWorld(plot.world);
@@ -266,6 +314,9 @@ public class DefaultPlotManager extends PlotManager {
         return false;
     }
 
+    /*
+     * Set a plot biome
+     */
     @Override
     public boolean setBiome(Player player, Plot plot, Biome biome) {
         
@@ -289,7 +340,9 @@ public class DefaultPlotManager extends PlotManager {
         return true;
     }
 
-    // PLOT MERGING
+    /*
+     * PLOT MERGING
+     */
     
     @Override
     public boolean createRoadEast(PlotWorld plotworld, Plot plot) {

PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotWorld.java

@@ -17,6 +17,12 @@ import com.intellectualcrafters.plot.PlotWorld;
 
 public class DefaultPlotWorld extends PlotWorld {
 
+    /*
+     * These variables are set to ensure fast access to config settings
+     * Strings are used as little as possible to optimize math performance in many of the functions/algorithms
+     * 
+     */
+    
     public boolean AUTO_MERGE;
     public static boolean AUTO_MERGE_DEFAULT = false;
     public boolean MOB_SPAWNING;
@@ -182,10 +188,21 @@ public class DefaultPlotWorld extends PlotWorld {
     public double MERGE_PRICE;
     public static double MERGE_PRICE_DEFAULT = 100;
     
+    
+    /*
+     * Here we are just calling the super method, nothing special
+     */
     public DefaultPlotWorld(String worldname) {
         super(worldname);
     }
 
+    /*
+     * CONFIG NODE | DEFAULT VALUE | DESCRIPTION | CONFIGURATION TYPE | REQUIRED FOR INITIAL SETUP
+     * 
+     * Set the last boolean to false if you do not require a specific config node to be set while using the setup command
+     *  - this may be useful if a config value can be changed at a later date, and has no impact on the actual world generation
+     * 
+     */
     @Override
     public ConfigurationNode[] getSettingNodes() {
         // TODO return a set of configuration nodes (used for setup command)
@@ -217,6 +234,10 @@ public class DefaultPlotWorld extends PlotWorld {
             };
     }
 
+    /*
+     * This method is called when a world loads. Make sure you set all your constants here.
+     * You are provided with the configuration section for that specific world.
+     */
     @Override
     public void loadConfiguration(ConfigurationSection config) {
         this.MOB_SPAWNING = config.getBoolean("natural_mob_spawning");

PlotSquared/src/com/intellectualcrafters/plot/generator/WorldGenerator.java

@@ -20,6 +20,10 @@ import com.intellectualcrafters.plot.PlotWorld;
  * @auther Empire92
  * @author Citymonstret
  * 
+ * The default generator is very messy, as we have decided to try externalize all calculations from within the loop.
+ *  - You will see a lot of slower implementations have a single for loop.
+ *  - This is perfectly fine to do, it will just mean world generation may take somewhat longer
+ * 
  */
 public class WorldGenerator extends PlotGenerator {
     /*

PlotSquared/src/com/intellectualcrafters/plot/generator/XPopulator.java

@@ -16,6 +16,14 @@ import com.intellectualcrafters.plot.PlotWorld;
  * 
  */
 public class XPopulator extends BlockPopulator {
+    
+    /*
+     * Sorry, this isn't well documented at the moment.
+     * 
+     * We advise you to take a look at a world generation tutorial for information about how a BlockPopulator works.
+     * 
+     */
+    
     private int X;
     private int Z;
     private long state;