From e494a15afab35dd44e7f31b472ba6ca519307f5c Mon Sep 17 00:00:00 2001 From: walterhiggins Date: Fri, 8 Feb 2013 21:23:15 +0000 Subject: [PATCH] Generate API doc from source comments --- build.xml | 13 +- docs/api.md | 388 +++++++++++++++++++++++++ src/docs/java/jscript.java | 13 + src/docs/javascript/generateApiDocs.js | 74 +++++ 4 files changed, 486 insertions(+), 2 deletions(-) create mode 100644 docs/api.md create mode 100644 src/docs/java/jscript.java create mode 100644 src/docs/javascript/generateApiDocs.js diff --git a/build.xml b/build.xml index 1241a2a..6ee213f 100644 --- a/build.xml +++ b/build.xml @@ -15,13 +15,22 @@ - + + + + + + + + + + - diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..7e27dff --- /dev/null +++ b/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. + diff --git a/src/docs/java/jscript.java b/src/docs/java/jscript.java new file mode 100644 index 0000000..b5d5cca --- /dev/null +++ b/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)); + } +} diff --git a/src/docs/javascript/generateApiDocs.js b/src/docs/javascript/generateApiDocs.js new file mode 100644 index 0000000..1ca2f5f --- /dev/null +++ b/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(adirbdir) 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]); + } +}