Generate API doc from source comments

build.xml

@@ -15,13 +15,22 @@
     </javac>
   </target>
     
-    
+  <target name="gendocs" description="Generate API documentation">
+    <javac srcdir="src/docs/java"/>
+    <java classname="jscript" failonerror="true" fork="true" output="docs/api.md">
+      <classpath>
+        <pathelement path="src/docs/java"/>      
+      </classpath>
+      <arg value="src/docs/javascript/generateApiDocs.js"/>
+      <arg value="src/main/javascript"/>
+    </java>
+  </target>
 
   <target name="zip_js">
     <zip zipfile="${build}/js-plugins.zip" basedir="./src/main/javascript"/>
   </target>
 
-  <target name="package" depends="zip_js,compile" 
+  <target name="package" depends="gendocs,zip_js,compile" 
           description="generate the distribution" >
     <copy file="src/main/resources/plugin.yml" todir="${build}"/>
     <replace file="${build}/plugin.yml" value="${bukkit-version}-${DSTAMP}">

docs/api.md

@@ -0,0 +1,388 @@
+Drone Module
+============
+The Drone is a convenience class for building. It can be used for...
+
+ 1. Building
+ 2. Copying and Pasting
+
+It uses a fluent interface which means all of the Drone's methods return `this` and can 
+be chained together like so...
+
+    var theDrone = new Drone();
+    theDrone.up().left().box(blocks.oak).down().fwd(3).cylinder0(blocks.lava,8); 
+
+TLDNR; (Just read this if you're impatient)
+===========================================
+At the in-game command prompt type...
+     
+    /js box(5)  
+    
+... creates a single wooden block at the cross-hairs or player location
+    
+    /js box(5).right(2).box('35:15',4,9,1)
+    
+... creates a single wooden block and a 2001 black obelisk that is 4
+wide x 9 tall x 1 long in size.  If you want to see what else
+ScriptCraft's Drone can do, read on...
+
+Constructing a Drone Object
+===========================
+
+Drones can be created in 3 ways...
+    
+ 1. Calling any one of the methods listed below will return a Drone object. For example...
+         
+        var d = box(blocks.oak)
+
+   ... creates a 1x1x1 wooden block at the cross-hairs or player's location and returns a Drone
+   object. This might look odd (if you're familiar with Java's Object-dot-method syntax) but all 
+   of the Drone class's methods are also global functions that return new Drone objects. 
+   This is short-hand for creating drones and is useful for playing around with Drones at the in-game 
+   command prompt. It's shorter than typing ...
+    
+        var d = new Drone().box(5) 
+        
+   ... All of the Drone's methods return `this` (self) so you can chain operations together like this...
+        
+        var d = box(5).up().box(5,3,1,3).down().fwd(2).box(5).turn().fwd(2).box(5).turn().fwd(2).box(5)
+    
+ 2. Using the following form...
+
+        d = new Drone()
+    
+    ...will create a new Drone. If the cross-hairs are pointing at a
+    block at the time then, that block's location becomes the drone's
+    starting point.  If the cross-hairs are _not_ pointing at a block,
+    then the drone's starting location will be 2 blocks directly in
+    front of the player.  TIP: Building always happens right and front
+    of the drone's position...
+    
+    Plan View:
+
+        ^
+        |
+        |
+        D---->
+      
+    For convenience you can use a _corner stone_ to begin building.
+    The corner stone should be located just above ground level.  If
+    the cross-hair is point at or into ground level when you create a
+    new Drone(), then building begins at that point. You can get
+    around this by pointing at a 'corner stone' just above ground
+    level or alternatively use the following statement...
+    
+        d = new Drone().up()
+          
+    ... which will move the drone up one block as soon as it's created.
+    
+ 3. Or by using the following form...
+    
+        d = new Drone(x,y,z,direction)
+
+    This will create a new Drone at the location you specified using
+    x, y, z In minecraft, the X axis runs west to east and the Z axis runs
+    north to south.  The direction parameter says what direction you want
+    the drone to face: 0 = east, 1 = south, 2 = west, 3 = north.  If the
+    direction parameter is omitted, the player's direction is used
+    instead.
+
+Parameters
+----------
+ * x (optional) : The x coordinate of the Drone
+ * y (optional) : The y coordinate of the Drone
+ * z (optional) : The z coordinate of the Drone
+ * direction (optional) : The direction in which the Drone is
+   facing. Possible values are 0 (east), 1 (south), 2 (west) or 3 (north)
+
+Drone.box() method
+==================
+the box() method is a convenience method for building things. (For the more performance-oriented method - see cuboid)
+
+parameters
+----------
+ * b - the block id - e.g. 6 for an oak sapling or '6:2' for a birch sapling. 
+   Alternatively you can use any one of the `blocks` values e.g. `blocks.sapling.birch`
+ * w (optional - default 1) - the width of the structure 
+ * h (optional - default 1) - the height of the structure 
+ * d (optional - default 1) - the depth of the structure - NB this is
+   not how deep underground the structure lies - this is how far
+   away (depth of field) from the drone the structure will extend.
+
+Example
+-------
+To create a stone structure 5 blocks wide, 8 blocks tall and 15 blocks long...
+    
+    drone.box(48, 5, 8, 15);
+    
+To create an oak tree...(we can't control the dimensions of a tree since it's a natural object in minecraft)
+
+    drone.box(6);
+
+Drone Movement
+==============
+Drones can move freely in minecraft's 3-D world. You control the
+Drone's movement using any of the following methods..
+
+ * up()
+ * down()
+ * left()
+ * right()
+ * fwd()
+ * back()
+ * turn()
+
+... Each of these methods takes a single optional parameter
+`numBlocks` - the number of blocks to move in the given direction. If
+no parameter is given, the default is 1.
+
+to change direction use the `turn()` method which also takes a single
+optional parameter (numTurns) - the number of 90 degree turns to make.
+Turns are always clock-wise. If the drone is facing north, then
+drone.turn() will make the turn face east. If the drone is facing east
+then drone.turn(2) will make the drone turn twice so that it is facing
+west.
+
+Drone Markers
+=============
+Markers are useful when your Drone has to do a lot of work. You can
+set a check-point and return to the check-point using the move()
+method.  If your drone is about to undertake a lot of work -
+e.g. building a road, skyscraper or forest you should set a
+check-point before doing so if you want your drone to return to its
+current location.  
+
+
+A 'start' checkpoint is automatically created when the Drone is first created.
+
+Markers are created and returned to using the followng two methods...
+
+ * chkpt - Saves the drone's current location so it can be returned to later.
+ * move - moves the drone to a saved location.
+
+Parameters
+----------
+ * name - the name of the checkpoint to save or return to.
+
+Example
+-------
+
+    drone.chkpt('town-square');
+    //
+    // the drone can now go off on a long excursion
+    //
+    for (i = 0; i< 100; i++){ 
+        drone.fwd(12).box(6); 
+    }
+    //
+    // return to the point before the excursion
+    //
+    drone.move('town-square');
+
+Drone.box0() method
+===================
+Another convenience method - this one creates 4 walls with no floor or ceiling.
+
+Parameters
+----------
+ * block - the block id - e.g. 6 for an oak sapling or '6:2' for a birch sapling. 
+   Alternatively you can use any one of the `blocks` values e.g. `blocks.sapling.birch`
+ * width (optional - default 1) - the width of the structure 
+ * height (optional - default 1) - the height of the structure 
+ * length (optional - default 1) - the length of the structure - how far
+   away (depth of field) from the drone the structure will extend.
+
+Drone.boxa() method
+===================
+Construct a cuboid using an array of blocks.
+
+Parameters
+----------
+ * blocks - An array of blocks - each block in the array will be placed in turn.
+ * width
+ * height
+ * length
+
+Example
+-------
+Construct a rainbow-colored road 100 blocks long...
+    var rainbowColors = [blocks.wool.red, blocks.wool.orange, blocks.wool.yellow, blocks.wool.lime,
+                   blocks.wool.lightblue, blocks.wool.blue, blocks.wool.purple];
+    boxa(rainbowColors,7,1,100);
+Drone.prism() method
+====================
+Creates a prism. This is useful for roofs on houses.
+
+Parameters
+----------
+
+ * block - the block id - e.g. 6 for an oak sapling or '6:2' for a birch sapling. 
+   Alternatively you can use any one of the `blocks` values e.g. `blocks.sapling.birch`
+ * width - the width of the prism
+ * length - the length of the prism (also its height)
+
+Drone.prism0() method
+=====================
+A variation on `prism` which hollows out the inside of the prism. It uses the same parameters as `prism`.
+
+Drone.cylinder() method
+=======================
+A convenience method for building cylinders. Building begins radius blocks to the right and forward.
+
+Parameters
+----------
+
+ * block - the block id - e.g. 6 for an oak sapling or '6:2' for a birch sapling. 
+   Alternatively you can use any one of the `blocks` values e.g. `blocks.sapling.birch`
+ * radius 
+ * height
+
+Drone.cylinder0() method
+========================
+A version of cylinder that hollows out the middle.
+Drone.door() method
+===================
+create a door - if a parameter is supplied an Iron door is created otherwise a wooden door is created.
+
+Parameters
+----------
+ * doorType (optional - default wood) - If a parameter is provided then the door is Iron.
+
+Drone.door2() method
+====================
+Create double doors (left and right side)
+
+Parameters
+----------
+ * doorType (optional - default wood) - If a parameter is provided then the door is Iron.
+
+Drone.sign method
+=================
+Signs must use block 63 (stand-alone signs) or 68 (signs on walls)
+
+Parameters
+----------
+ * message -  can be a string or an array of strings. 
+ * block - can be 63 or 68
+
+Example
+-------
+To create a free-standing sign...
+
+    drone.sign(["Hello","World"],63);
+
+... to create a wall mounted sign...
+
+    drone.sign(["Message","Goes","Here"], 68);
+
+Drone Trees methods
+===================
+
+ * oak()
+ * spruce()
+ * birch()
+ * jungle()
+
+None of the tree methods require parameters. Tree methods will only be successful
+if the tree is placed on grass in a setting where trees can grow.
+Drone.rand() method
+===================
+rand takes either an array (if each blockid has the same chance of occurring)
+or an object where each property is a blockid and the value is it's weight (an integer)
+
+Example
+-------
+place random blocks stone, mossy stone and cracked stone (each block has the same chance of being picked)
+
+    rand( [blocks.brick.stone, blocks.brick.mossy, blocks.brick.cracked ],w,d,h) 
+
+to place random blocks stone has a 50% chance of being picked, 
+
+    rand({blocks.brick.stone: 5, blocks.brick.mossy: 3, blocks.brick.cracked: 2},w,d,h) 
+
+regular stone has a 50% chance, mossy stone has a 30% chance and cracked stone has just a 20% chance of being picked.
+
+Drone.garden() method
+=====================
+places random flowers and long grass (similar to the effect of placing bonemeal on grass)
+
+Parameters
+----------
+
+ * width - the width of the garden
+ * length - how far from the drone the garden extends
+
+Copy & Paste using Drone
+========================
+A drone can be used to copy and paste areas of the game world.
+
+Drone.copy() method
+===================
+Copies an area so it can be pasted elsewhere. The name can be used for
+pasting the copied area elsewhere...
+
+Parameters
+----------
+
+ * name - the name to be given to the copied area (used by `paste`)
+ * width - the width of the area to copy
+ * height - the height of the area to copy
+ * length - the length of the area (extending away from the drone) to copy
+
+Example
+-------
+    drone.copy('somethingCool',10,5,10).right(12).paste('somethingCool');
+
+Drone.paste() method
+====================
+Pastes a copied area to the current location.
+
+Example
+-------
+To copy a 10x5x10 area (using the drone's coordinates as the starting
+point) into memory.  the copied area can be referenced using the name
+'somethingCool'. The drone moves 12 blocks right then pastes the copy.
+
+    drone.copy('somethingCool',10,5,10)
+         .right(12)
+         .paste('somethingCool');
+
+Chaining
+========
+
+All of the Drone methods return a Drone object, which means methods
+can be 'chained' together so instead of writing this...
+
+    drone = new Drone(); 
+    drone.fwd(3);
+    drone.left(2);
+    drone.box(2); // create a grass block
+    drone.up();
+    drone.box(2); // create another grass block
+    drone.down();
+
+...you could simply write ...
+    
+    var drone = new Drone().fwd(3).left(2).box(2).up().box(2).down();
+
+... since each Drone method is also a global function that constructs
+a drone if none is supplied, you can shorten even further to just...
+    
+    fwd(3).left(2).box(2).up().box(2).down()
+
+The Drone object uses a [Fluent Interface][fl] to make ScriptCraft
+scripts more concise and easier to write and read.  Minecraft's
+in-game command prompt is limited to about 80 characters so chaining
+drone commands together means more can be done before hitting the
+command prompt limit. For complex building you should save your
+commands in a new script file and load it using /js load()
+
+[fl]: http://en.wikipedia.org/wiki/Fluent_interface
+
+Drone Properties
+================
+
+ * x - The Drone's position along the west-east axis (x increases as you move east)
+ * y - The Drone's position along the vertical axis (y increses as you move up)
+ * z - The Drone's position along the north-south axis (z increases as you move south)
+ * dir - The Drone's direction 0 is east, 1 is south , 2 is west and 3 is north.
+

src/docs/java/jscript.java

@@ -0,0 +1,13 @@
+import javax.script.*;
+public class jscript
+{
+    public static void main(String[] args) throws Exception
+    {
+        ScriptEngineManager factory = new ScriptEngineManager();
+        ScriptEngine engine = factory.getEngineByName("JavaScript");
+        java.io.File file = new java.io.File(args[0]);
+        engine.put("engine",engine);
+        engine.put("args",args);
+        engine.eval(new java.io.FileReader(file));
+    }
+}

src/docs/javascript/generateApiDocs.js

@@ -0,0 +1,74 @@
+/*
+  This script is run at build time to generate api.md - a single Markdown document containing documentation for ScriptCraft's API
+*/
+args = args.slice(1);
+var dir = args[0];
+importPackage(java.io);
+/*
+  find - a (very) basic implementation of the unix command line tool.
+*/
+var find = function(dir,store,re) 
+{
+    var files = dir.listFiles();
+    for (var i = 0;i < files.length; i++){
+        var file = new File(files[i]);
+        if (file.isDirectory()) {
+            find(file,store,re);
+        } else {
+            if (typeof re == "undefined") 
+                store.push(files[i]);
+            else if ((""+files[i]).match(re)) 
+                store.push(files[i]);
+        }
+    }
+};
+/*
+  the main module file for a given directory
+  (assuming the main module is in a file with the same name as the parent 
+  directory) - e.g. drone/drone.js 
+*/
+var sortByModule = function(a,b){
+    var aparts = (""+a).split(/\//);
+    var bparts = (""+b).split(/\//);
+    var adir = aparts[aparts.length-2];
+    var afile = aparts[aparts.length-1];
+    var bdir = bparts[bparts.length-2];
+    var bfile = bparts[bparts.length-1];
+
+    if(adir<bdir) return -1;
+    if(adir>bdir) return 1;
+    if (afile.indexOf(adir) == 0)
+        return -1;
+    else
+        return 1;
+};
+var store = [];
+find(new File(dir),store,/\.js$/);
+store.sort(sortByModule);
+var contents = [];
+for (var i =0; i < store.length; i++){
+    var br = new BufferedReader(new FileReader(store[i]));
+    var line ;
+    while ( (line = br.readLine()) != null){
+        contents.push(line);
+    }
+    br.close();
+}
+var len = contents.length;
+var writeComment = false;
+var startComment = /^\/\*{10}/;
+var endComment = /^\*{3}\//;
+
+for (var i = 0; i < len; i++){
+    var line = contents[i];
+    if (line.match(startComment)){
+        writeComment = true;
+        i++;
+    }
+    if (line.match(endComment)){
+        writeComment = false;
+    }
+    if (writeComment){
+        println(contents[i]);
+    }
+}