[Bleeding] Clean up and clarify javadocs on new generator methods.

1 files changed, 64 insertions, 34 deletions

diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
index db579cdc..768fa396 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
@@ -69,28 +69,43 @@ public abstract class ChunkGenerator {
     }
 
     /**
-     * Shapes the chunk for the given coordinates.<br />
-     * <br />
-     * This method should return a short[][] array in the following format:
-     *
+     * Shapes the chunk for the given coordinates, with extended block IDs supported (0-4095).
+     * <p>
+     * As of 1.2, chunks are represented by a vertical array of chunk sections, each of which is 16 x 16 x 16 blocks.  If a section
+     * is empty (all zero), the section does not need to be supplied, reducing memory usage.
+     * <p>
+     * This method must return a short[][] array in the following format:
      * <pre>
-     * result[y >> 4] = null IF the 16x16x16 section from y to y+15 is empty
-     * result[y >> 4] = new short[4096] if the section has any non-empty blocks
-     *
-     * within the section:
-     *
-     * for (int x = 0; x &lt; 16; x++) {
-     *     for (int z = 0; z &lt; 16; z++) {
-     *         for (int yy = y & 0xF; yy &lt; 16; yy++) {
-     *             result[(yy << 8) | (z << 4) | x] = ??;
-     *         }
-     *     }
-     * }
+     *     short[][] result = new short[world-height / 16][];
+     * </pre>    
+     * Each section (sectionID = (Y>>4)) that has blocks needs to be allocated space for the 4096 blocks in that section:
+     * <pre>
+     *     result[sectionID] = new short[4096];
      * </pre>
-     *
+     * while sections that are not populated can be left null.
+     * <p>
+     * Setting a block at X, Y, Z within the chunk can be done with the following mapping function:
+     * <pre>
+     *    void setBlock(short[][] result, int x, int y, int z, short blkid) {
+     *        if (result[y >> 4) == null) {
+     *            result[y >> 4] = new short[4096];
+     *        }
+     *        result[y >> 4][((y & 0xF) << 8) | (z << 4) | x] = blkid;
+     *    }
+     * </pre>
+     * while reading a block ID can be done with the following mapping function:
+     * <pre>
+     *    short getBlock(short[][] result, int x, int y, int z) {
+     *        if (result[y >> 4) == null) {
+     *            return (short)0;
+     *        }
+     *        return result[y >> 4][((y & 0xF) << 8) | (z << 4) | x];
+     *    }
+     * </pre>
+     * <p>
      * Note that this method should <b>never</b> attempt to get the Chunk at
      * the passed coordinates, as doing so may cause an infinite loop
-     *
+     * <p>
      * Note generators that do not return block IDs above 255 should not implement
      * this method, or should have it return null (which will result in the
      * generateBlockSections() method being called).
@@ -107,23 +122,38 @@ public abstract class ChunkGenerator {
     }
 
     /**
-     * Shapes the chunk for the given coordinates.<br />
-     * <br />
-     * This method should return a byte[][] array in the following format:
-     *
+     * Shapes the chunk for the given coordinates.
+     * <p>
+     * As of 1.2, chunks are represented by a vertical array of chunk sections, each of which is 16 x 16 x 16 blocks.  If a section
+     * is empty (all zero), the section does not need to be supplied, reducing memory usage.
+     * <p>
+     * This method must return a byte[][] array in the following format:
      * <pre>
-     * result[y >> 4] = null IF the 16x16x16 section from y to y+15 is empty
-     * result[y >> 4] = new byte[4096] if the section has any non-empty blocks
-     *
-     * within the section:
-     *
-     * for (int x = 0; x &lt; 16; x++) {
-     *     for (int z = 0; z &lt; 16; z++) {
-     *         for (int yy = y & 0xF; yy &lt; 16; yy++) {
-     *             result[(yy << 8) | (z << 4) | x] = ??;
-     *         }
-     *     }
-     * }
+     *     byte[][] result = new byte[world-height / 16][];
+     * </pre>    
+     * Each section (sectionID = (Y>>4)) that has blocks needs to be allocated space for the 4096 blocks in that section:
+     * <pre>
+     *     result[sectionID] = new byte[4096];
+     * </pre>
+     * while sections that are not populated can be left null.
+     * <p>
+     * Setting a block at X, Y, Z within the chunk can be done with the following mapping function:
+     * <pre>
+     *    void setBlock(byte[][] result, int x, int y, int z, byte blkid) {
+     *        if (result[y >> 4) == null) {
+     *            result[y >> 4] = new byte[4096];
+     *        }
+     *        result[y >> 4][((y & 0xF) << 8) | (z << 4) | x] = blkid;
+     *    }
+     * </pre>
+     * while reading a block ID can be done with the following mapping function:
+     * <pre>
+     *    byte getBlock(byte[][] result, int x, int y, int z) {
+     *        if (result[y >> 4) == null) {
+     *            return (byte)0;
+     *        }
+     *        return result[y >> 4][((y & 0xF) << 8) | (z << 4) | x];
+     *    }
      * </pre>
      *
      * Note that this method should <b>never</b> attempt to get the Chunk at