updated docs/comments

docs/api.md

@@ -1,4 +1,4 @@
-ScriptCraft API Reference
+/************************************************************************
 =========================
 
 Walter Higgins
@@ -219,7 +219,7 @@ There are a couple of special javascript variables available in ScriptCraft...
  * server - The Minecraft Server object.
  * self - the current player. (Note - this value should not be used in multi-threaded scripts - it's not thread-safe)
 
-refresh() function
+/*************************************************************************
 ------------------
 The refresh() function will ...
 
@@ -232,83 +232,7 @@ See [issue #69][issue69] for more information.
 
 [issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
 
-classroom Module
+/*********************************************************************
-================
-Utility functions for use in a classroom setting. The goal of these
-functions is to make it easier for tutors to facilitate ScriptCraft
-for use by students.
-  
-classroom.allowScripting() function
-===================================
-Allow or disallow anyone who connects to the server (or is already
-connected) to use ScriptCraft. This function is preferable to granting 'ops' privileges 
-to every student in a Minecraft classroom environment.
-
-Parameters
-----------
-
- * canScript : true or false
-
-Example
--------
-To allow all players (and any players who connect to the server) to
-use the `js` and `jsp` commands...
-
-    /js classroom.allowScripting(true)
-
-To disallow scripting (and prevent players who join the server from using the commands)...
-
-    /js classroom.allowScripting(false)
-
-Only ops users can run the classroom.allowScripting() function - this is so that students 
-don't try to bar themselves and each other from scripting.
-
-Drone.spiral_stairs() method
-============================
-Constructs a spiral staircase with slabs at each corner.
-
-Parameters
-----------
-
- * stairBlock - The block to use for stairs, should be one of the following...
-   - 'oak'
-   - 'spruce'
-   - 'birch'
-   - 'jungle'
-   - 'cobblestone'
-   - 'brick'
-   - 'stone'
-   - 'nether'
-   - 'sandstone'
-   - 'quartz'
- * flights - The number of flights of stairs to build.
-
-![Spiral Staircase](img/spiralstair1.png)
-
-Example
--------
-To construct a spiral staircase 5 floors high made of oak...
-
-    spiral_stairs('oak', 5);
-
-Drone.rainbow() method
-======================
-Creates a Rainbow.
-
-Parameters
-----------
-
- * radius (optional - default:18) - The radius of the rainbow
-
-Example
--------
-    
-    var d = new Drone();
-    d.rainbow(30);
-
-![rainbow example](img/rainbowex1.png)
-
-Drone Module
 ============
 The Drone is a convenience class for building. It can be used for...
 
@@ -407,7 +331,7 @@ Parameters
    facing. Possible values are 0 (east), 1 (south), 2 (west) or 3 (north)
  * world (optional) : The world in which the drone is created.
 
-Drone.box() method
+/************************************************************************
 ==================
 the box() method is a convenience method for building things. (For the more performance-oriented method - see cuboid)
 
@@ -478,7 +402,7 @@ Construct a rainbow-colored road 100 blocks long...
 
 ![boxa example](img/boxaex1.png)
 
-Drone Movement
+/************************************************************************
 ==============
 Drones can move freely in minecraft's 3-D world. You control the
 Drone's movement using any of the following methods..
@@ -502,12 +426,12 @@ 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 Positional Info
+/************************************************************************
 =====================
 
  * getLocation() - Returns a Bukkit Location object for the drone
 
-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()
@@ -543,7 +467,7 @@ Example
     //
     drone.move('town-square');
 
-Drone.prism() method
+/************************************************************************
 ====================
 Creates a prism. This is useful for roofs on houses.
 
@@ -566,7 +490,7 @@ 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.
 
@@ -598,7 +522,7 @@ To create a hollow cylinder of Iron 7 blocks in radius and 1 block high...
 
 ![cylinder0 example](img/cylinder0ex1.png)
 
-Drone.arc() method
+/************************************************************************
 ==================
 The arc() method can be used to create 1 or more 90 degree arcs in the horizontal or vertical planes.
 This method is called by cylinder() and cylinder0() and the sphere() and sphere0() methods.
@@ -644,7 +568,7 @@ To draw a 1/4 circle (top right quadrant only) with a radius of 10 and stroke wi
 
 [bres]: http://en.wikipedia.org/wiki/Midpoint_circle_algorithm
 [dv]: http://www.minecraftwiki.net/wiki/Data_values
-Drone.door() method
+/************************************************************************
 ===================
 create a door - if a parameter is supplied an Iron door is created otherwise a wooden door is created.
 
@@ -681,7 +605,7 @@ To create double-doors at the cross-hairs/drone's location...
 
 ![double doors](img/door2ex1.png)
 
-Drone.sign() method
+/************************************************************************
 ===================
 Signs must use block 63 (stand-alone signs) or 68 (signs on walls)
 
@@ -704,7 +628,7 @@ To create a free-standing sign...
 
 ![wall sign](img/signex2.png)
 
-Drone Trees methods
+/************************************************************************
 ===================
 
  * oak()
@@ -729,7 +653,7 @@ the `up()` method is called first).
     
 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.garden() method
+/************************************************************************
 =====================
 places random flowers and long grass (similar to the effect of placing bonemeal on grass)
 
@@ -747,7 +671,7 @@ To create a garden 10 blocks wide by 5 blocks long...
 
 ![garden example](img/gardenex1.png)
 
-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)
@@ -764,7 +688,7 @@ to place random blocks stone has a 50% chance of being picked,
 
 regular stone has a 50% chance, mossy stone has a 30% chance and cracked stone has just a 20% chance of being picked.
 
-Copy & Paste using Drone
+/************************************************************************
 ========================
 A drone can be used to copy and paste areas of the game world.
 
@@ -800,7 +724,7 @@ point) into memory.  the copied area can be referenced using the name
          .right(12)
          .paste('somethingCool');
 
-Chaining
+/************************************************************************
 ========
 
 All of the Drone methods return a Drone object, which means methods
@@ -910,7 +834,7 @@ Used when placing torches so that they face towards the drone.
 
     drone.box( blocks.torch + ':' + Drone.PLAYER_TORCH_FACING[drone.dir]);
 
-Drone.times() Method
+/**************************************************************************
 ====================
 The times() method makes building multiple copies of buildings easy. It's possible to create rows or grids of buildings without resorting to `for` or `while` loops.
 
@@ -975,100 +899,7 @@ Another example: This statement creates a row of trees 2 by 3 ...
 
 ![times example 1](img/times-trees.png)
 
-Drone.sphere() method
+/************************************************************************
-=====================
-Creates a sphere.
-
-Parameters
-----------
- 
- * block - The block the sphere will be made of.
- * radius - The radius of the sphere.
-
-Example
--------
-To create a sphere of Iron with a radius of 10 blocks...
-
-    sphere( blocks.iron, 10);
-
-![sphere example](img/sphereex1.png)
-
-Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
-server to be very busy for a couple of minutes while doing so.
-
-Drone.sphere0() method
-======================
-Creates an empty sphere.
-
-Parameters
-----------
- 
- * block - The block the sphere will be made of.
- * radius - The radius of the sphere.
-
-Example
--------
-To create a sphere of Iron with a radius of 10 blocks...
-
-    sphere0( blocks.iron, 10);
-
-Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
-server to be very busy for a couple of minutes while doing so.
-
-Drone.hemisphere() method
-=========================
-Creates a hemisphere. Hemispheres can be either north or south.
-
-Parameters
-----------
-
- * block - the block the hemisphere will be made of.
- * radius - the radius of the hemisphere
- * northSouth - whether the hemisphere is 'north' or 'south'
-
-Example
--------
-To create a wood 'north' hemisphere with a radius of 7 blocks...
-
-    hemisphere(blocks.oak, 7, 'north');
-
-![hemisphere example](img/hemisphereex1.png)
-
-Drone.hemisphere0() method
-=========================
-Creates a hollow hemisphere. Hemispheres can be either north or south.
-
-Parameters
-----------
-
- * block - the block the hemisphere will be made of.
- * radius - the radius of the hemisphere
- * northSouth - whether the hemisphere is 'north' or 'south'
-
-Example
--------
-To create a glass 'north' hemisphere with a radius of 20 blocks...
-
-    hemisphere0(blocks.glass, 20, 'north');
-
-![hemisphere example](img/hemisphereex2.png)
-
-Blocks Module
-=============
-You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I.
-So I created this blocks object which is a helper object for use in construction.
-
-Examples
---------
-
-    box( blocks.oak ); // creates a single oak wood block
-    box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long
-    box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide
-
-In addition, each of the wool colors is also available as a block property so you can use either
-`blocks.wool.green` or the more concise `blocks.green`. There's also a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations). 
-
-Drone.blocktype() method
 ========================
 Creates the text out of blocks. Useful for large-scale in-game signs.
 
@@ -1089,7 +920,186 @@ To create a 2-line high message using glowstone...
 
 [imgbt1]: img/blocktype1.png
 
-events Module
+/************************************************************************
+=============
+You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I.
+So I created this blocks object which is a helper object for use in construction.
+
+Examples
+--------
+
+    box( blocks.oak ); // creates a single oak wood block
+    box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long
+    box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide
+
+In addition, each of the wool colors is also available as a block property so you can use either
+`blocks.wool.green` or the more concise `blocks.green`. There's also a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations). 
+
+/************************************************************************
+=====================
+Creates a sphere.
+
+Parameters
+----------
+ 
+ * block - The block the sphere will be made of.
+ * radius - The radius of the sphere.
+
+Example
+-------
+To create a sphere of Iron with a radius of 10 blocks...
+
+    sphere( blocks.iron, 10);
+
+![sphere example](img/sphereex1.png)
+
+Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
+server to be very busy for a couple of minutes while doing so.
+
+/************************************************************************
+======================
+Creates an empty sphere.
+
+Parameters
+----------
+ 
+ * block - The block the sphere will be made of.
+ * radius - The radius of the sphere.
+
+Example
+-------
+To create a sphere of Iron with a radius of 10 blocks...
+
+    sphere0( blocks.iron, 10);
+
+Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
+server to be very busy for a couple of minutes while doing so.
+
+/************************************************************************
+=========================
+Creates a hemisphere. Hemispheres can be either north or south.
+
+Parameters
+----------
+
+ * block - the block the hemisphere will be made of.
+ * radius - the radius of the hemisphere
+ * northSouth - whether the hemisphere is 'north' or 'south'
+
+Example
+-------
+To create a wood 'north' hemisphere with a radius of 7 blocks...
+
+    hemisphere(blocks.oak, 7, 'north');
+
+![hemisphere example](img/hemisphereex1.png)
+
+/************************************************************************
+=========================
+Creates a hollow hemisphere. Hemispheres can be either north or south.
+
+Parameters
+----------
+
+ * block - the block the hemisphere will be made of.
+ * radius - the radius of the hemisphere
+ * northSouth - whether the hemisphere is 'north' or 'south'
+
+Example
+-------
+To create a glass 'north' hemisphere with a radius of 20 blocks...
+
+    hemisphere0(blocks.glass, 20, 'north');
+
+![hemisphere example](img/hemisphereex2.png)
+
+/************************************************************************
+======================
+Creates a Rainbow.
+
+Parameters
+----------
+
+ * radius (optional - default:18) - The radius of the rainbow
+
+Example
+-------
+    
+    var d = new Drone();
+    d.rainbow(30);
+
+![rainbow example](img/rainbowex1.png)
+
+/************************************************************************
+============================
+Constructs a spiral staircase with slabs at each corner.
+
+Parameters
+----------
+
+ * stairBlock - The block to use for stairs, should be one of the following...
+   - 'oak'
+   - 'spruce'
+   - 'birch'
+   - 'jungle'
+   - 'cobblestone'
+   - 'brick'
+   - 'stone'
+   - 'nether'
+   - 'sandstone'
+   - 'quartz'
+ * flights - The number of flights of stairs to build.
+
+![Spiral Staircase](img/spiralstair1.png)
+
+Example
+-------
+To construct a spiral staircase 5 floors high made of oak...
+
+    spiral_stairs('oak', 5);
+
+/************************************************************************
+================
+The `classroom` object contains a couple of utility functions for use
+in a classroom setting. The goal of these functions is to make it
+easier for tutors to facilitate ScriptCraft for use by students in a
+classroom environment. Although granting ScriptCraft access to
+students on a shared server is potentially risky (Students can
+potentially abuse it), it is slighlty less risky than granting
+operator privileges to each student. (Enterprising students will
+quickly realise how to grant themselves and others operator privileges
+once they have access to ScriptCraft).
+
+The goal of this module is not so much to enforce restrictions
+(security or otherwise) but to make it easier for tutors to setup a shared server
+so students can learn Javascript.
+
+classroom.allowScripting() function
+===================================
+Allow or disallow anyone who connects to the server (or is already
+connected) to use ScriptCraft. This function is preferable to granting 'ops' privileges 
+to every student in a Minecraft classroom environment.
+
+Parameters
+----------
+
+ * canScript : true or false
+
+Example
+-------
+To allow all players (and any players who connect to the server) to
+use the `js` and `jsp` commands...
+
+    /js classroom.allowScripting(true)
+
+To disallow scripting (and prevent players who join the server from using the commands)...
+
+    /js classroom.allowScripting(false)
+
+Only ops users can run the classroom.allowScripting() function - this is so that students 
+don't try to bar themselves and each other from scripting.
+
+/************************************************************************
 =============
 The Events module provides a thin wrapper around Bukkit's
 Event-handling API.  Bukkit's Events API makes use of Java Annotations
@@ -1156,7 +1166,7 @@ To unregister a listener *outside* of the listener function...
 [buk2]: http://wiki.bukkit.org/Event_API_Reference
 [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html
 
-http.request() function
+/*************************************************************************
 ====================
 The http.request() function will fetch a web address asynchronously (on a
 separate thread)and pass the URL's response to a callback function
@@ -1195,7 +1205,7 @@ The following example illustrates how to use http.request to make a request to a
           var jsObj = eval("(" + responseBody + ")");
       });
 
-Utilities Module
+/************************************************************************
 ================
 Miscellaneous utility functions and classes to help with programming.
 
@@ -1204,7 +1214,7 @@ Miscellaneous utility functions and classes to help with programming.
  * getPlayerObject(playerName) - returns the Player object for a named
    player or `self` if no name is provided.
 
-utils.foreach() function
+/************************************************************************
 ========================
 The utils.foreach() function is a utility function for iterating over
 an array of objects (or a java.util.Collection of objects) and processing each object in turn. Where
@@ -1278,7 +1288,7 @@ without hogging CPU usage...
     };
     foreach (a, processItem, null, 10, onDone);
     
-utils.nicely() function
+/************************************************************************
 =======================
 The utils.nicely() function is for performing processing using the
 [org.bukkit.scheduler][sched] package/API. utils.nicely() lets you
@@ -1302,7 +1312,7 @@ Example
 -------
 See the source code to utils.foreach for an example of how utils.nicely is used.
 
-String class extensions
+/************************************************************************
 -----------------------
 The following chat-formatting methods are added to the javascript String class..
 

src/docs/javascript/generateApiDocs.js

@@ -3,6 +3,12 @@
 */
 args = args.slice(1);
 var dir = args[0];
+var foreach = function(array, func){
+    for (var i =0; i < array.length; i++){
+        func(array[i],i,array);
+    }
+};
+
 importPackage(java.io);
 /*
   find - a (very) basic implementation of the unix command line tool.
@@ -10,23 +16,53 @@ importPackage(java.io);
 var find = function(dir,store,re) 
 {
     var files = dir.listFiles();
-    for (var i = 0;i < files.length; i++){
+    foreach (files, function(filename){
-        var file = new File(files[i]);
+        filename = "" + filename;
+        var file = new File(filename);
         if (file.isDirectory()) {
             find(file,store,re);
         } else {
             if (typeof re == "undefined") 
-                store.push(files[i]);
+                store.push(filename);
-            else if ((""+files[i]).match(re)) 
+            else if (filename.match(re)) 
-                store.push(files[i]);
+                store.push(filename);
-        }
         }
+    });
 };
 /*
   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 sorter = function( precedence ){
+    return function(a,b)
+    {
+        // convert from Java string to JS string
+        a = "" + a; 
+        b = "" + b;
+        var aparts = a.split(/\//);
+        var bparts = b.split(/\//);
+        var adir = aparts.slice(3,aparts.length-1).join("/");
+        var afile = aparts[aparts.length-1];
+        var bdir = bparts.slice(3,bparts.length-1).join("/");
+        var bfile = bparts[bparts.length-1];
+
+        for (var i = 0;i < precedence.length; i++){
+            var re = precedence[i];
+            if (a.match(re))
+                return -1;
+            if (b.match(re))
+                return 1;
+        }
+        if(adir<bdir) return -1;
+        if(adir>bdir) return 1;
+        afile = afile.replace(/\.js$/,"");
+        if (afile == adir)
+            return -1;
+        else
+            return 1;
+    };
+};
 var sortByModule = function(a,b)
 {
     var aparts = (""+a).split(/\//);
@@ -49,25 +85,29 @@ var sortByModule = function(a,b)
 var store = [];
 find(new File(dir),store,/\/[a-zA-Z0-9_\-]+\.js$/);
 
-store.sort(sortByModule);
+store.sort(sorter([ 
+        /_scriptcraft\.js$/, 
+        /core/, 
+        /drone\.js/, 
+        /drone/
+]));
 
 var contents = [];
-for (var i =0; i < store.length; i++)
+foreach(store, function(filename){
-{
+    var br = new BufferedReader(new FileReader(filename));
-    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++) 
+for (var i = 0;i < contents.length; i++){
-{
     var line = contents[i];
     if (line.match(startComment)){
         writeComment = true;
@@ -77,6 +117,7 @@ for (var i = 0; i < len; i++)
         writeComment = false;
     }
     if (writeComment){
-        println(contents[i]);
+        println(line);
     }
 }
+

src/main/javascript/classroom/classroom.js

@@ -1,13 +1,20 @@
 /************************************************************************
-classroom Module
+Classroom Module
 ================
-Utility functions for use in a classroom setting. The goal of these
+The `classroom` object contains a couple of utility functions for use
-functions is to make it easier for tutors to facilitate ScriptCraft
+in a classroom setting. The goal of these functions is to make it
-for use by students.
+easier for tutors to facilitate ScriptCraft for use by students in a
+classroom environment. Although granting ScriptCraft access to
+students on a shared server is potentially risky (Students can
+potentially abuse it), it is slighlty less risky than granting
+operator privileges to each student. (Enterprising students will
+quickly realise how to grant themselves and others operator privileges
+once they have access to ScriptCraft).
 
-***/
+The goal of this module is not so much to enforce restrictions
+(security or otherwise) but to make it easier for tutors to setup a shared server
+so students can learn Javascript.
 
-/*************************************************************************
 classroom.allowScripting() function
 ===================================
 Allow or disallow anyone who connects to the server (or is already
@@ -46,7 +53,6 @@ ready(function(){
          */
         if (!self.isOp())
             return;
-
         if (canScript){
             utils.foreach( server.onlinePlayers, function (player) {
                 player.addAttachment(__plugin, "scriptcraft.*", true);
@@ -65,7 +71,8 @@ ready(function(){
     };
     events.on("player.PlayerLoginEvent", function(listener, event) { 
         var player = event.player;
-        if (classroom.canScript)
+        if (classroom.canScript){
             player.addAttachment(__plugin, "scriptcraft.*", true);
+        }
     }, "HIGHEST");
 });