Generate API doc from source comments
This commit is contained in:
walterhiggins
parent
903c701f6f
commit
e494a15afa
13
build.xml
13
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}">
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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));
|
||||
}
|
||||
}
|
||||
|
|
@ -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]);
|
||||
}
|
||||
}
|
||||
Reference in New Issue