From cdc8ad7d9b381a8f5e9809221085109629dd245e Mon Sep 17 00:00:00 2001
From: walterhiggins <walter.higgins@gmail.com>
Date: Tue, 31 Dec 2013 21:09:50 +0000
Subject: [PATCH] Tweaks to documentation (examples and all files in same
 directory sorted alphabetically except where precedence regexp present)

---
 docs/API-Reference.md                         | 774 +++++++++---------
 src/docs/javascript/generateApiDocs.js        |  59 +-
 .../examples/example-5-hello-using-module.js  |  17 +-
 .../examples/example-6-hello-player.js        |  15 +-
 4 files changed, 447 insertions(+), 418 deletions(-)

diff --git a/docs/API-Reference.md b/docs/API-Reference.md
index 16624ca..70249b5 100644
--- a/docs/API-Reference.md
+++ b/docs/API-Reference.md
@@ -570,92 +570,6 @@ To listen for events using a full class name as the `eventName` parameter...
 [buk2]: http://wiki.bukkit.org/Event_API_Reference
 [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html
 
-## Example Plugin #7
-
-A simple event-driven minecraft plugin. How to handle Events.
-
-
-This example demonstrates event-driven programming. The code below
-will display the version of ScriptCraft every time an operator joins
-the game. This module is notable from previous modules for the
-following reasons...
-
- 1. It does not export any functions or variables. That's fine. Not
-    all modules need export stuff. Code in this module will be
-    executed when the module is first loaded. Because it is in the
-    `/scriptcraft/plugins` directory, it will be loaded automatically
-    when the server starts up.
-
- 2. It uses ScriptCraft's `events.on()` function to add a new *Event
-    Handler*. An *Event Handler* is a just a function which gets
-    called whenever a particular *event* happens in the game. The
-    function defined below will only be executed whenever a player
-    joins the game. This style of program is sometimes refered to as
-    *Event-Driven Programming*.
-
-Adding new *Event Handlers* in ScriptCraft is relatively easy. Use the
-`events.on()` function to add a new event handler. It takes 2
-parameters...
-
- 1. The Event Name, in this case `'player.PlayerJoinEvent'`. You can
-    browse [all possible Bukkit events][bkevts] (click the 'Next
-    Package' and 'Previous Package' links to browse).
-
- 2. The event handling function (also sometimes refered to as a
-    'callback'). In ScriptCraft, this function takes 2 parameters, a
-    listener object and an event object. All of the information about
-    the event is in the event object.
-
-In the example below, if a player joins the server and is an operator,
-then the ScriptCraft plugin information will be displayed to that
-player.
-
-What's also notable about this example is how it uses the [Bukkit
-API][bkapi]. The code...
-
-    if (event.player.op)
-
-... is a succinct way of accessing object properties which in Java
-would have to be written as ...
-
-    if (event.getPlayer().isOp())
-
-... ScriptCraft uses a special version of JavaScript which comes
-bundled with Java (Minecraft is written in Java) and JavaScript in
-Java can access properties of Java objects more succinctly than in
-Java itself. What this means in practice is that when you're perusing
-the [Bukkit API Reference][bkapi] and come across a method like
-[Player.getAllowFlight()][bkgaf], you can write code like this...
-
-    var allowFlight = player.getAllowFlight(); // java style
-
-... or the more succinct ...
-
-    var allowFlight = player.allowFlight; // javascript style
-
-... Which style you choose is up to you but `player.allowFlight` is
-cleaner and more readable. Similarly where you see a method like
-[Player.setAllowFlight()][bksaf], you can write ...
-
-    player.setAllowFlight(true); // java style
-
-... or the more readable...
-
-    player.allowFlight = true; // javascript style
-
-... Which style you choose is up to you.
-
-[bkevts]: http://jd.bukkit.org/dev/apidocs/org/bukkit/event/package-summary.html
-[bkgaf]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html#getAllowFlight()
-[bksaf]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html#setAllowFlight()
-[bkapi]: http://jd.bukkit.org/dev/apidocs/
-
-    events.on('player.PlayerJoinEvent', function (listener, event){
-        if (event.player.op) {
-            event.player.sendMessage('Welcome to ' + __plugin);
-        }
-    });
-
 ## console global variable
 
 ScriptCraft provides a `console` global variable with the followng methods...
@@ -690,6 +604,58 @@ ScriptCraft uses Java's [String.format()][strfmt] so any string substitution ide
 [strfmt]: http://docs.oracle.com/javase/6/docs/api/java/lang/String.html#format(java.lang.String, java.lang.Object...)
 [webcons]: https://developer.mozilla.org/en-US/docs/Web/API/console
 
+## 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
+
+Color aliased properties that were a direct descendant of the blocks
+object are no longer used to avoid confusion with carpet and stained
+clay blocks. In addition, there's a convenience array `blocks.rainbow`
+which is an array of the 7 colors of the rainbow (or closest
+approximations).
+
+The blocks module is globally exported by the Drone module.
+
+## Fireworks Module
+
+The fireworks module makes it easy to create fireworks using
+ScriptCraft.  The module has a single function `firework` which takes
+a `org.bukkit.Location` as its 1 and only parameter.
+
+### Examples
+
+The module also extends the `Drone` object adding a `firework` method
+so that fireworks can be created as a part of a Drone chain. For
+Example....
+
+    /js firework()
+
+... creates a single firework, while ....
+
+    /js firework().fwd(3).times(5) 
+
+... creates 5 fireworks in a row. Fireworks have also been added as a
+possible option for the `arrow` module. To have a firework launch
+where an arrow strikes...
+
+    /js arrows.firework()
+
+To call the fireworks.firework() function directly, you must provide a
+location. For example...
+
+    /js var fireworks = require('fireworks');
+    /js fireworks.firework(self.location);
+
+![firework example](img/firework.png)
+
 ## http.request() function
 
 The http.request() function will fetch a web address asynchronously (on a
@@ -730,6 +696,47 @@ The following example illustrates how to use http.request to make a request to a
           var jsObj = eval("(" + responseBody + ")");
       });
 
+String class extensions
+-----------------------
+The following chat-formatting methods are added to the javascript String class..
+
+    * aqua()
+    * black()
+    * blue()
+    * bold()
+    * brightgreen()
+    * darkaqua()
+    * darkblue()
+    * darkgray()
+    * darkgreen()
+    * purple()
+    * darkpurple()
+    * darkred()
+    * gold()
+    * gray()
+    * green()
+    * italic()
+    * lightpurple()
+    * indigo()
+    * green()
+    * red()
+    * pink()
+    * yellow()
+    * white()
+    * strike()
+    * random()
+    * magic()
+    * underline()
+    * reset()
+
+Example
+-------
+
+    /js var boldGoldText = "Hello World".bold().gold();
+    /js self.sendMessage(boldGoldText);
+
+<p style="color:gold;font-weight:bold">Hello World</p>    
+
 ## Utilities Module
 
 The `utils` module is a storehouse for various useful utility
@@ -1001,99 +1008,6 @@ a given directory and recursiving trawling all sub-directories.
         return name.match(/\.js$/);
     });  
 
-String class extensions
------------------------
-The following chat-formatting methods are added to the javascript String class..
-
-    * aqua()
-    * black()
-    * blue()
-    * bold()
-    * brightgreen()
-    * darkaqua()
-    * darkblue()
-    * darkgray()
-    * darkgreen()
-    * purple()
-    * darkpurple()
-    * darkred()
-    * gold()
-    * gray()
-    * green()
-    * italic()
-    * lightpurple()
-    * indigo()
-    * green()
-    * red()
-    * pink()
-    * yellow()
-    * white()
-    * strike()
-    * random()
-    * magic()
-    * underline()
-    * reset()
-
-Example
--------
-
-    /js var boldGoldText = "Hello World".bold().gold();
-    /js self.sendMessage(boldGoldText);
-
-<p style="color:gold;font-weight:bold">Hello World</p>    
-
-## 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
-
-Color aliased properties that were a direct descendant of the blocks
-object are no longer used to avoid confusion with carpet and stained
-clay blocks. In addition, there's a convenience array `blocks.rainbow`
-which is an array of the 7 colors of the rainbow (or closest
-approximations).
-
-The blocks module is globally exported by the Drone module.
-
-## Fireworks Module
-
-The fireworks module makes it easy to create fireworks using
-ScriptCraft.  The module has a single function `firework` which takes
-a `org.bukkit.Location` as its 1 and only parameter.
-
-### Examples
-
-The module also extends the `Drone` object adding a `firework` method
-so that fireworks can be created as a part of a Drone chain. For
-Example....
-
-    /js firework()
-
-... creates a single firework, while ....
-
-    /js firework().fwd(3).times(5) 
-
-... creates 5 fireworks in a row. Fireworks have also been added as a
-possible option for the `arrow` module. To have a firework launch
-where an arrow strikes...
-
-    /js arrows.firework()
-
-To call the fireworks.firework() function directly, you must provide a
-location. For example...
-
-    /js var fireworks = require('fireworks');
-    /js fireworks.firework(self.location);
-
-![firework example](img/firework.png)
-
 Drone Module
 ============
 The Drone is a convenience class for building. It can be used for...
@@ -1813,6 +1727,21 @@ To create a 2-line high message using glowstone...
 
 [imgbt1]: img/blocktype1.png
 
+## 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.sphere() method
 
 Creates a sphere.
@@ -1887,21 +1816,6 @@ To create a glass 'north' hemisphere with a radius of 20 blocks...
 
 ![hemisphere example](img/hemisphereex2.png)
 
-## 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.spiral_stairs() method
 
 Constructs a spiral staircase with slabs at each corner.
@@ -1929,6 +1843,272 @@ To construct a spiral staircase 5 floors high made of oak...
 
     spiral_stairs('oak', 5);
 
+## Example Plugin #1
+
+A simple minecraft plugin. The most basic module.
+
+### Usage: 
+
+At the in-game prompt type ...
+  
+    /js hello(self)
+
+... and a message `Hello {player-name}` will appear (where
+  {player-name} is replaced by your own name).
+  
+This example demonstrates the basics of adding new functionality which
+is only usable by server operators or users with the
+scriptcraft.evaluate permission. By default, only ops are granted this
+permission.
+  
+The `hello` function below is only usable by players with the scriptcraft.evaluate 
+permission since it relies on the `/js` command to execute.
+
+    exports.hello = function(player){
+        player.sendMessage('Hello ' + player.name);
+    };
+
+## Example Plugin #2
+
+A simple minecraft plugin. Commands for other players.
+
+### Usage: 
+
+At the in-game prompt type ...
+  
+    /jsp hello
+
+... and a message `Hello {player-name}` will appear (where {player-name} is 
+replaced by your own name).
+  
+This example demonstrates the basics of adding new functionality
+which is usable all players or those with the scriptcraft.proxy
+permission.  By default, all players are granted this permission.
+  
+This differs from example 1 in that a new 'jsp ' command extension
+is defined. Since all players can use the `jsp` command, all players
+can use the new extension. Unlike the previous example, the `jsp hello` 
+command does not evaluate javascript code so this command is much more secure.
+
+    command('hello', function (parameters, player) {
+        player.sendMessage('Hello ' + player.name);
+    });
+
+## Example Plugin #3
+
+A simple minecraft plugin. Commands for operators only.
+
+### Usage: 
+
+At the in-game prompt type ...
+  
+    /jsp op-hello
+
+... and a message `Hello {player-name}` will appear (where {player-name} is 
+replaced by your own name).
+  
+This example demonstrates the basics of adding new functionality
+which is usable all players or those with the scriptcraft.proxy
+permission. By default, all players are granted this permission. In
+this command though, the function checks to see if the player is an
+operator and if they aren't will return immediately.
+ 
+This differs from example 2 in that the function will only print a
+message for operators.
+
+    command('op-hello', function (parameters, player) {
+        if (!player.op){
+            player.sendMessage('Only operators can do this.');
+            return;
+        }
+        player.sendMessage('Hello ' + player.name);
+    });
+## Example Plugin #4
+A simple minecraft plugin. Handling parameters.
+
+### Usage: 
+
+At the in-game prompt type ...
+  
+    /jsp hello-params Hi
+    /jsp hello-params Saludos 
+    /jsp hello-params Greetings
+
+... and a message `Hi {player-name}` or `Saludos {player-name}` etc
+will appear (where {player-name} is replaced by your own name).
+  
+This example demonstrates adding and using parameters in commands.
+  
+This differs from example 3 in that the greeting can be changed from
+a fixed 'Hello ' to anything you like by passing a parameter.
+
+    command('hello-params', function (parameters, player) {
+        var salutation = parameters[0] ;
+        player.sendMessage( salutation + ' ' + player.name);
+    });
+
+## Example Plugin #5
+
+A simple minecraft plugin. Using Modules.
+
+### Usage: 
+
+At the in-game prompt type ...
+  
+    /jsp hello-module
+
+... and a message `Hello {player-name}` will appear (where {player-name} is 
+replaced by your own name).
+  
+This example demonstrates the use of modules. In
+example-1-hello-module.js we created a new javascript module. In
+this example, we use that module...
+
+ * We load the module using the `require()` function. Because this
+   module and the module we require are n the same directory, we
+   specify `'./example-1-hello-module'` as the path (when loading a
+   module from the same directory, `./` at the start of the path
+   indicates that the file should be searched for in the same
+   directory.
+
+ * We assign the loaded module to a variable (`greetings`) and then
+   use the module's `hello` method to display the message. 
+
+Source Code...
+
+    var greetings = require('./example-1-hello-module');
+    command('hello-module', function( parameters, player ){
+        greetings.hello(player);
+    });
+
+## Example Plugin #6
+
+A simple minecraft plugin. Finding players by name.
+
+### Usage: 
+
+At the in-game prompt type ...
+  
+    /jsp hello-byname {player-name}
+
+... substituting {player-name} with the name of a player currently
+online and a message `Hello ...` will be sent to the named
+player.
+  
+This example builds on example-5 and also introduces a new concept -
+use of shared modules. That is : modules which are not specific to
+any one plugin or set of plugins but which can be used by all
+plugins. Shared modules should be placed in the
+`scriptcraft/modules` directory.
+  
+ * The utils module is used. Because the 'utils' module is
+   located in the modules folder we don't need to specify an exact
+   path, just 'utils' will do. 
+ 
+ * The `utils.player()` function is used to obtain a player object
+   matching the player name. Once a player object is obtained, a
+   message is sent to that player.
+
+Source Code ...
+
+    var utils = require('utils');
+    var greetings = require('./example-1-hello-module');
+
+    command('hello-byname', function( parameters, sender ) {
+        var playerName = parameters[0];
+        var recipient = utils.player(playerName);
+        if (recipient)
+            greetings.hello(recipient);
+        else
+            sender.sendMessage('Player ' + playerName + ' not found.');
+    });
+
+## Example Plugin #7
+
+A simple event-driven minecraft plugin. How to handle Events.
+
+
+This example demonstrates event-driven programming. The code below
+will display the version of ScriptCraft every time an operator joins
+the game. This module is notable from previous modules for the
+following reasons...
+
+ 1. It does not export any functions or variables. That's fine. Not
+    all modules need export stuff. Code in this module will be
+    executed when the module is first loaded. Because it is in the
+    `/scriptcraft/plugins` directory, it will be loaded automatically
+    when the server starts up.
+
+ 2. It uses ScriptCraft's `events.on()` function to add a new *Event
+    Handler*. An *Event Handler* is a just a function which gets
+    called whenever a particular *event* happens in the game. The
+    function defined below will only be executed whenever a player
+    joins the game. This style of program is sometimes refered to as
+    *Event-Driven Programming*.
+
+Adding new *Event Handlers* in ScriptCraft is relatively easy. Use the
+`events.on()` function to add a new event handler. It takes 2
+parameters...
+
+ 1. The Event Name, in this case `'player.PlayerJoinEvent'`. You can
+    browse [all possible Bukkit events][bkevts] (click the 'Next
+    Package' and 'Previous Package' links to browse).
+
+ 2. The event handling function (also sometimes refered to as a
+    'callback'). In ScriptCraft, this function takes 2 parameters, a
+    listener object and an event object. All of the information about
+    the event is in the event object.
+
+In the example below, if a player joins the server and is an operator,
+then the ScriptCraft plugin information will be displayed to that
+player.
+
+What's also notable about this example is how it uses the [Bukkit
+API][bkapi]. The code...
+
+    if (event.player.op)
+
+... is a succinct way of accessing object properties which in Java
+would have to be written as ...
+
+    if (event.getPlayer().isOp())
+
+... ScriptCraft uses a special version of JavaScript which comes
+bundled with Java (Minecraft is written in Java) and JavaScript in
+Java can access properties of Java objects more succinctly than in
+Java itself. What this means in practice is that when you're perusing
+the [Bukkit API Reference][bkapi] and come across a method like
+[Player.getAllowFlight()][bkgaf], you can write code like this...
+
+    var allowFlight = player.getAllowFlight(); // java style
+
+... or the more succinct ...
+
+    var allowFlight = player.allowFlight; // javascript style
+
+... Which style you choose is up to you but `player.allowFlight` is
+cleaner and more readable. Similarly where you see a method like
+[Player.setAllowFlight()][bksaf], you can write ...
+
+    player.setAllowFlight(true); // java style
+
+... or the more readable...
+
+    player.allowFlight = true; // javascript style
+
+... Which style you choose is up to you.
+
+[bkevts]: http://jd.bukkit.org/dev/apidocs/org/bukkit/event/package-summary.html
+[bkgaf]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html#getAllowFlight()
+[bksaf]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html#setAllowFlight()
+[bkapi]: http://jd.bukkit.org/dev/apidocs/
+
+    events.on('player.PlayerJoinEvent', function (listener, event){
+        if (event.player.op) {
+            event.player.sendMessage('Welcome to ' + __plugin);
+        }
+    });
+
 ## Arrows Module 
 
 The arrows mod adds fancy arrows to the game. Arrows which... 
@@ -2119,182 +2299,6 @@ global commands for a plugin, please let me know.
 
 [pcppevt]: http://jd.bukkit.org/dev/apidocs/org/bukkit/event/player/PlayerCommandPreprocessEvent.html
 
-## Example Plugin #5
-
-A simple minecraft plugin. Using Modules.
-
-### Usage: 
-
-At the in-game prompt type ...
-  
-    /jsp hello-module
-
-... and a message `Hello {player-name}` will appear (where {player-name} is 
-replaced by your own name).
-  
-This example demonstrates the use of modules. In
-example-1-hello-module.js we created a new javascript module. In
-this example, we use that module...
-
-  * We load the module using the `require()` function. Because this
-    module and the module we require are n the same directory, we
-    specify `'./example-1-hello-module'` as the path (when loading a
-    module from the same directory, `./` at the start of the path
-    indicates that the file should be searched for in the same
-    directory.
-
-  * We assign the loaded module to a variable (`greetings`) and then
-    use the module's `hello` method to display the message. 
-
-
-    var greetings = require('./example-1-hello-module');
-    command('hello-module', function( parameters, player ){
-        greetings.hello(player);
-    });
-
-## Example Plugin #3
-
-A simple minecraft plugin. Commands for operators only.
-
-### Usage: 
-
-At the in-game prompt type ...
-  
-    /jsp op-hello
-
-... and a message `Hello {player-name}` will appear (where {player-name} is 
-replaced by your own name).
-  
-This example demonstrates the basics of adding new functionality
-which is usable all players or those with the scriptcraft.proxy
-permission. By default, all players are granted this permission. In
-this command though, the function checks to see if the player is an
-operator and if they aren't will return immediately.
- 
-This differs from example 2 in that the function will only print a
-message for operators.
-
-    command('op-hello', function (parameters, player) {
-        if (!player.op){
-            player.sendMessage('Only operators can do this.');
-            return;
-        }
-        player.sendMessage('Hello ' + player.name);
-    });
-## Example Plugin #1
-
-A simple minecraft plugin. The most basic module.
-
-### Usage: 
-
-At the in-game prompt type ...
-  
-    /js hello(self)
-
-... and a message `Hello {player-name}` will appear (where
-  {player-name} is replaced by your own name).
-  
-This example demonstrates the basics of adding new functionality which
-is only usable by server operators or users with the
-scriptcraft.evaluate permission. By default, only ops are granted this
-permission.
-  
-The `hello` function below is only usable by players with the scriptcraft.evaluate 
-permission since it relies on the `/js` command to execute.
-
-    exports.hello = function(player){
-        player.sendMessage('Hello ' + player.name);
-    };
-
-## Example Plugin #6
-
-A simple minecraft plugin. Finding players by name.
-
-### Usage: 
-
-At the in-game prompt type ...
-  
-    /jsp hello-byname {player-name}
-
-... substituting {player-name} with the name of a player currently
-online and a message `Hello ...` will be sent to the named
-player.
-  
-This example builds on example-5 and also introduces a new concept -
-use of shared modules. That is : modules which are not specific to
-any one plugin or set of plugins but which can be used by all
-plugins. Shared modules should be placed in the
-`scriptcraft/modules` directory.
-  
-  * The utils module is used. Because the 'utils' module is
-    located in the modules folder we don't need to specify an exact
-    path, just 'utils' will do. 
- 
-  * The `utils.player()` function is used to obtain a player object
-    matching the player name. Once a player object is obtained, a
-    message is sent to that player.
-
-    var utils = require('utils');
-    var greetings = require('./example-1-hello-module');
-
-    command('hello-byname', function( parameters, sender ) {
-        var playerName = parameters[0];
-        var recipient = utils.player(playerName);
-        if (recipient)
-            greetings.hello(recipient);
-        else
-            sender.sendMessage('Player ' + playerName + ' not found.');
-    });
-## Example Plugin #2
-
-A simple minecraft plugin. Commands for other players.
-
-### Usage: 
-
-At the in-game prompt type ...
-  
-    /jsp hello
-
-... and a message `Hello {player-name}` will appear (where {player-name} is 
-replaced by your own name).
-  
-This example demonstrates the basics of adding new functionality
-which is usable all players or those with the scriptcraft.proxy
-permission.  By default, all players are granted this permission.
-  
-This differs from example 1 in that a new 'jsp ' command extension
-is defined. Since all players can use the `jsp` command, all players
-can use the new extension. Unlike the previous example, the `jsp hello` 
-command does not evaluate javascript code so this command is much more secure.
-
-    command('hello', function (parameters, player) {
-        player.sendMessage('Hello ' + player.name);
-    });
-
-## Example Plugin #4
-A simple minecraft plugin. Handling parameters.
-
-### Usage: 
-
-At the in-game prompt type ...
-  
-    /jsp hello-params Hi
-    /jsp hello-params Saludos 
-    /jsp hello-params Greetings
-
-... and a message `Hi {player-name}` or `Saludos {player-name}` etc
-will appear (where {player-name} is replaced by your own name).
-  
-This example demonstrates adding and using parameters in commands.
-  
-This differs from example 3 in that the greeting can be changed from
-a fixed 'Hello ' to anything you like by passing a parameter.
-
-    command('hello-params', function (parameters, player) {
-        var salutation = parameters[0] ;
-        player.sendMessage( salutation + ' ' + player.name);
-    });
-
 ## homes Module
 
 The homes plugin lets players set a location as home and return to the
@@ -2354,6 +2358,21 @@ The following administration options can only be used by server operators...
    the world, it simply removes the location from the database. No
    blocks are destroyed by this command.
 
+## NumberGuess mini-game: 
+
+### Description
+This is a very simple number guessing game. Minecraft will ask you to
+guess a number between 1 and 10 and you will tell you if you're too
+hight or too low when you guess wrong. The purpose of this mini-game
+code is to demonstrate use of Bukkit's Conversation API.
+
+### Example
+    
+    /js Game_NumberGuess.start(self)
+
+Once the game begins, guess a number by typing the `/` character
+followed by a number between 1 and 10.
+
 ## SnowballFight mini-game
 
 ### Description
@@ -2395,18 +2414,3 @@ player returns to their previous mode of play (creative or
 survival). Create a small arena with a couple of small buildings for
 cover to make the game more fun.
   
-## NumberGuess mini-game: 
-
-### Description
-This is a very simple number guessing game. Minecraft will ask you to
-guess a number between 1 and 10 and you will tell you if you're too
-hight or too low when you guess wrong. The purpose of this mini-game
-code is to demonstrate use of Bukkit's Conversation API.
-
-### Example
-    
-    /js Game_NumberGuess.start(self)
-
-Once the game begins, guess a number by typing the `/` character
-followed by a number between 1 and 10.
-
diff --git a/src/docs/javascript/generateApiDocs.js b/src/docs/javascript/generateApiDocs.js
index 8577523..c0ca1b9 100644
--- a/src/docs/javascript/generateApiDocs.js
+++ b/src/docs/javascript/generateApiDocs.js
@@ -1,6 +1,8 @@
 /*
   This script is run at build time to generate api.md - a single Markdown document containing documentation for ScriptCraft's API
 */
+var err = java.lang.System.err;
+
 args = args.slice(1);
 var dir = args[0];
 var foreach = function(array, func){
@@ -38,17 +40,23 @@ var sorter = function( precedence ){
     return function(a,b)
     {
         // convert from Java string to JS string
-        a = "" + a; 
-        b = "" + b;
+        a = '' + a; 
+        b = '' + b;
         var aparts = a.split(/\//);
         var bparts = b.split(/\//);
-        var adir = aparts.slice(3,aparts.length-1).join("/");
+        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 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) && b.match(re)){
+                if (afile < bfile)
+                    return -1;
+                if (afile > bfile)
+                    return 1;
+            }
             if (a.match(re))
                 return -1;
             if (b.match(re))
@@ -56,24 +64,35 @@ var sorter = function( precedence ){
         }
         if(adir<bdir) return -1;
         if(adir>bdir) return 1;
-        afile = afile.replace(/\.js$/,"");
-        if (afile == adir)
+        afile = afile.replace(/\.js$/,'');
+        if (afile == adir){
             return -1;
-        else
-            return 1;
+        }
+        else {
+            var result = 0;
+            if (afile < bfile){
+                result =  -1;
+            }
+            if (afile > bfile){
+                result = 1;
+            }
+            //err.println("afile: " + afile + ", bfile:" + bfile + ",result=" + result);
+            
+            return result;
+        }
     };
 };
 var sortByModule = function(a,b)
 {
-    var aparts = (""+a).split(/\//);
-    var bparts = (""+b).split(/\//);
+    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 (afile == "_scriptcraft.js")
+    if (afile == '_scriptcraft.js')
         return -1;
-    if (bfile == "_scriptcraft.js")
+    if (bfile == '_scriptcraft.js')
         return 1;
     if(adir<bdir) return -1;
     if(adir>bdir) return 1;
@@ -86,15 +105,17 @@ var store = [];
 find(new File(dir),store,/\/[a-zA-Z0-9_\-]+\.js$/);
 
 store.sort(sorter([ 
-        /scriptcraft\.js$/, 
-        /require\.js$/,
-        /plugin\.js$/,
-        /events\.js$/,
-        /lib/, 
-        /modules/,
+        /lib\/scriptcraft\.js$/, 
+        /lib\/require\.js$/,
+        /lib\/plugin\.js$/,
+        /lib\/events\.js$/,
+        /lib\//, 
+        /modules\//,
         /drone\.js/, 
-        /drone/
+        /drone\//,
+        /examples\//
 ]));
+//err.println("store=" + JSON.stringify(store));
 
 var contents = [];
 foreach(store, function(filename){
diff --git a/src/main/javascript/plugins/examples/example-5-hello-using-module.js b/src/main/javascript/plugins/examples/example-5-hello-using-module.js
index a335033..80ae39f 100644
--- a/src/main/javascript/plugins/examples/example-5-hello-using-module.js
+++ b/src/main/javascript/plugins/examples/example-5-hello-using-module.js
@@ -16,16 +16,17 @@ This example demonstrates the use of modules. In
 example-1-hello-module.js we created a new javascript module. In
 this example, we use that module...
 
-  * We load the module using the `require()` function. Because this
-    module and the module we require are n the same directory, we
-    specify `'./example-1-hello-module'` as the path (when loading a
-    module from the same directory, `./` at the start of the path
-    indicates that the file should be searched for in the same
-    directory.
+ * We load the module using the `require()` function. Because this
+   module and the module we require are n the same directory, we
+   specify `'./example-1-hello-module'` as the path (when loading a
+   module from the same directory, `./` at the start of the path
+   indicates that the file should be searched for in the same
+   directory.
 
-  * We assign the loaded module to a variable (`greetings`) and then
-    use the module's `hello` method to display the message. 
+ * We assign the loaded module to a variable (`greetings`) and then
+   use the module's `hello` method to display the message. 
 
+Source Code...
 
     var greetings = require('./example-1-hello-module');
     command('hello-module', function( parameters, player ){
diff --git a/src/main/javascript/plugins/examples/example-6-hello-player.js b/src/main/javascript/plugins/examples/example-6-hello-player.js
index 924d92c..0d1971b 100644
--- a/src/main/javascript/plugins/examples/example-6-hello-player.js
+++ b/src/main/javascript/plugins/examples/example-6-hello-player.js
@@ -19,13 +19,15 @@ any one plugin or set of plugins but which can be used by all
 plugins. Shared modules should be placed in the
 `scriptcraft/modules` directory.
   
-  * The utils module is used. Because the 'utils' module is
-    located in the modules folder we don't need to specify an exact
-    path, just 'utils' will do. 
+ * The utils module is used. Because the 'utils' module is
+   located in the modules folder we don't need to specify an exact
+   path, just 'utils' will do. 
  
-  * The `utils.player()` function is used to obtain a player object
-    matching the player name. Once a player object is obtained, a
-    message is sent to that player.
+ * The `utils.player()` function is used to obtain a player object
+   matching the player name. Once a player object is obtained, a
+   message is sent to that player.
+
+Source Code ...
 
     var utils = require('utils');
     var greetings = require('./example-1-hello-module');
@@ -38,6 +40,7 @@ plugins. Shared modules should be placed in the
         else
             sender.sendMessage('Player ' + playerName + ' not found.');
     });
+
 ***/
 
 var utils = require('utils');