Added documentation for the 'homes' module ( issue #105)

docs/API-Reference.md

@@ -127,27 +127,67 @@ As of December 24 2013, the `scriptcraft/plugins` directory has the following su
  * alias - The alias plugin/module - for creating custom aliases for commonly used commands.
  * home - The home module - for setting homes and visiting other homes.
 
+## Global variables
+
+There are a couple of special javascript variables available in ScriptCraft...
+ 
+### __plugin variable
+The ScriptCraft JavaPlugin object.
+
+### server variable
+The Minecraft Server object
+
+### self variable
+The current player. (Note - this value should not be used in multi-threaded scripts or event-handling code - it's not thread-safe)
+
+### config variable
+ScriptCraft configuration - this object is loaded and saved at startup/shutdown.
+
+### events variable
+The events object is used to add new event handlers to Minecraft.
+
+## Module variables
+The following variables are available only within the context of Modules. (not available at in-game prompt).
+
+### __filename variable
+The current file - this variable is only relevant from within the context of a Javascript module.
+
+### __dirname variable
+The current directory - this variable is only relevant from within the context of a Javascript module.
+
 ## Global functions
 
 ScripCraft provides some global functions which can be used by all plugins/modules...
 
 ### echo function
 
-The `echo()` function displays a message on the in-game screen. The message is displayed to the `self` player (this is usually the player who issued the `/js` or `/jsp` command).
+The `echo()` function displays a message on the in-game screen. The
+message is displayed to the `self` player (this is usually the player
+who issued the `/js` or `/jsp` command).
 
 ### Example
 
     /js echo('Hello World')
 
+For programmers familiar with Javascript web programming, an `alert`
+function is also provided.  `alert` works exactly the same as `echo`
+e.g. `alert('Hello World')`.
 
-* echo (message) - Displays a message on the screen. 
+### Notes
-   For example: `/js echo('Hello World')` will print Hello World on the in-game chat window.  
+
-   For programmers familiar with Javascript web programming, an `alert` function is also provided. 
+The `echo` and `alert` functions are provided as convenience functions
-   `alert` works exactly the same as `echo` e.g. `alert('Hello World')`. 
+for beginning programmers. The use of these 2 functions is not
+recommended in event-handling code or multi-threaded code. In such
+cases, if you want to send a message to a given player then use the
+Bukkit API's [Player.sendMessage()][plsm] function instead.
+
+[plsm]: 
 
  * require (modulename) - Will load modules. See [Node.js modules][njsmod]
 
- * load (filename,warnOnFileNotFound) - loads and evaluates a javascript file, returning the evaluated object. (Note: Prefer `require()` to `load()`)
+ * load (filename,warnOnFileNotFound) - loads and evaluates a
+   javascript file, returning the evaluated object. (Note: Prefer
+   `require()` to `load()`)
   
  * save (object, filename) - saves an object to a file.
 
@@ -164,8 +204,9 @@ The `echo()` function displays a message on the in-game screen. The message is d
 
 ### require() function
 
-ScriptCraft's `require()` function is used to load modules. The `require()` function takes a 
+ScriptCraft's `require()` function is used to load modules. The
-module name as a parameter and will try to load the named module.
+`require()` function takes a module name as a parameter and will try
+to load the named module.
 
 #### Parameters
 
@@ -258,7 +299,8 @@ persist data.
  
  * pluginName (String) : The name of the plugin - this becomes a global variable.
  * pluginDefinition (Object) : The various functions and members of the plugin object.
- * isPersistent (boolean - optional) : Specifies whether or not the plugin/object state should be loaded and saved by ScriptCraft.
+ * isPersistent (boolean - optional) : Specifies whether or not the
+   plugin/object state should be loaded and saved by ScriptCraft.
 
 #### Example
 
@@ -290,25 +332,18 @@ plugin author) safely expose javascript functions for use by players.
 
 #### Example
 
-See chat/colors.js or alias/alias.js or homes/homes.js for examples of how to use the `command()` function.
+See chat/colors.js or alias/alias.js or homes/homes.js for examples of
-
+how to use the `command()` function.
-## global variables
-
-There are a couple of special javascript variables available in ScriptCraft...
- 
- * __folder - The current working directory - this variable is only to be used within the main body of a .js file.
- * __plugin - The ScriptCraft JavaPlugin object.
- * 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)
-
-## Miscellaneous Core Functions
 
 ### setTimeout() function
 
-This function mimics the setTimeout() function used in browser-based javascript.
+This function mimics the setTimeout() function used in browser-based
-However, the function will only accept a function reference, not a string of javascript code.
+javascript.  However, the function will only accept a function
-Where setTimeout() in the browser returns a numeric value which can be subsequently passed to 
+reference, not a string of javascript code.  Where setTimeout() in the
-clearTimeout(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearTimeout() implementation.
+browser returns a numeric value which can be subsequently passed to
+clearTimeout(), This implementation returns a [BukkitTask][btdoc]
+object which can be subsequently passed to ScriptCraft's own
+clearTimeout() implementation.
 
 If Node.js supports setTimeout() then it's probably good for ScriptCraft to support it too.
 
@@ -330,12 +365,16 @@ A scriptcraft implementation of clearTimeout().
 
 ### setInterval() function
 
-This function mimics the setInterval() function used in browser-based javascript.
+This function mimics the setInterval() function used in browser-based
-However, the function will only accept a function reference, not a string of javascript code.
+javascript.  However, the function will only accept a function
-Where setInterval() in the browser returns a numeric value which can be subsequently passed to 
+reference, not a string of javascript code.  Where setInterval() in
-clearInterval(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearInterval() implementation.
+the browser returns a numeric value which can be subsequently passed
+to clearInterval(), This implementation returns a [BukkitTask][btdoc]
+object which can be subsequently passed to ScriptCraft's own
+clearInterval() implementation.
 
-If Node.js supports setInterval() then it's probably good for ScriptCraft to support it too.
+If Node.js supports setInterval() then it's probably good for
+ScriptCraft to support it too.
 
 [btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
 
@@ -356,6 +395,13 @@ See [issue #69][issue69] for more information.
 
 [issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
 
+### addUnloadHandler() function
+
+The addUnloadHandler() function takes a callback function as a
+parameter. The callback will be called when the ScriptCraft plugin is
+unloaded (usually as a result of a a `reload` command or server
+shutdown).
+
 ## require - Node.js-style module loading in ScriptCraft
 
 Node.js is a server-side javascript environment with an excellent
@@ -1874,9 +1920,68 @@ global commands for a plugin, please let me know.
 
 [pcppevt]: http://jd.bukkit.org/dev/apidocs/org/bukkit/event/player/PlayerCommandPreprocessEvent.html
 
-# SnowballFight mini-game
+## homes Module
 
-## Description
+The homes plugin lets players set a location as home and return to the
+location, invite other players to their home and also visit other
+player's homes.
+
+This module is a good example of how to create a javascript-based
+minecraft mod which provides...
+
+ * A programmatic interface (API) and 
+ * A command extension which uses that API to provide new functionality for players.
+
+The module uses the `plugin()` function to specify an object and
+methods, and the `command()` function to expose functionality to
+players through a new `jsp home` command. This module also
+demonstrates how to enable autocompletion for custom commands (to see
+this in action, at the in-game prompt or server console prompt type
+`jsp home ` then press the TAB key - you should see a list of further
+possible options).
+
+The `jsp home` command has the following options...
+
+### Basic options
+
+ * `/jsp home set` Will set your current location as your
+   'home' location to which you can return at any time using the ...
+
+ * `/jsp home` ..command will return you to your home, if you have set one.
+
+ * `/jsp home <player>` Will take you to the home of <player> (where 
+   <player> is the name of the player whose home you wish to visit.
+
+ * `/jsp home delete` Deletes your home location from the location
+   database. This does not actually remove the home from the world or
+   change the world in any way. This command is completely
+   non-destructive and cannot be used for griefing. No blocks will be
+   destroyed by this command.
+
+### Social options
+The following options allow players to open their homes to all or some
+players, invite players to their home and see a list of homes they can
+visit.
+
+ * `/jsp home list` Lists home which you can visit.
+ * `/jsp home ilist` Lists players who can visit your home.
+ * `/jsp home invite <player>` Invites the named player to your home.
+ * `/jsp home uninvite <player>` Uninvites (revokes invitation) the named player to your home.
+ * `/jsp home public` Opens your home to all players (all players can visit your home).
+ * `/jsp home private` Makes your home private (no longer visitable by all).
+
+### Administration options
+The following administration options can only be used by server operators...
+
+ * `/jsp home listall` List all of the homes
+ * `/jsp home clear <player>` Removes the player's home
+   location. Again, this command does not destroy any structures in
+   the world, it simply removes the location from the database. No
+   blocks are destroyed by this command.
+
+## SnowballFight mini-game
+
+### Description
 
 This is a rough and ready prototype of a simple multi-player
 shoot-em-up. To start a game with all players playing against one another...
@@ -1915,15 +2020,15 @@ 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: 
+## NumberGuess mini-game: 
 
-## Description
+### 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
+### Example
     
     /js Game_NumberGuess.start()
 

src/main/javascript/lib/console.js

@@ -34,6 +34,7 @@ ScriptCraft uses Java's [String.format()][strfmt] so any string substitution ide
 [webcons]: https://developer.mozilla.org/en-US/docs/Web/API/console
 
 ***/
+var logger = __plugin.logger;
 var argsToArray = function(args){
     var result = [];
     for (var i =0;i < args.length; i++)

src/main/javascript/lib/plugin.js

@@ -1,3 +1,4 @@
+var console = require('./console');
 var File = java.io.File;
 var FileWriter = java.io.FileWriter;
 var PrintWriter = java.io.PrintWriter;
@@ -88,7 +89,7 @@ var _command = function(name,func,options,intercepts)
             try { 
                 result =  func(params);
             }catch (e){
-                logger.severe("Error while trying to execute command: " + JSON.stringify(params));
+                console.error("Error while trying to execute command: " + JSON.stringify(params));
                 throw e;
             }
             return result;
@@ -150,17 +151,22 @@ exports.autoload = function(dir) {
 
         var len = sourceFiles.length;
         if (config.verbose)
-            logger.info(len + " scriptcraft plugins found.");
+            console.info(len + " scriptcraft plugins found.");
         for (var i = 0;i < len; i++){
             var pluginPath = _canonize(sourceFiles[i]);
             if (config.verbose)
-                logger.info("Loading plugin: " + pluginPath);
+                console.info("Loading plugin: " + pluginPath);
-            var module = require(pluginPath);
+            var module = {};
-            for (var property in module){
+            try {
-                /*
+                module = require(pluginPath);
-                  all exports in plugins become global
+                for (var property in module){
-                 */
+                    /*
-                global[property] = module[property];
+                      all exports in plugins become global
+                    */
+                    global[property] = module[property];
+                }
+            }catch (e){
+                
             }
         }
     };

src/main/javascript/lib/scriptcraft.js

@@ -1,4 +1,3 @@
-var global = this;
 /************************************************************************
 # ScriptCraft API Reference
 
@@ -129,27 +128,67 @@ As of December 24 2013, the `scriptcraft/plugins` directory has the following su
  * alias - The alias plugin/module - for creating custom aliases for commonly used commands.
  * home - The home module - for setting homes and visiting other homes.
 
+## Global variables
+
+There are a couple of special javascript variables available in ScriptCraft...
+ 
+### __plugin variable
+The ScriptCraft JavaPlugin object.
+
+### server variable
+The Minecraft Server object
+
+### self variable
+The current player. (Note - this value should not be used in multi-threaded scripts or event-handling code - it's not thread-safe)
+
+### config variable
+ScriptCraft configuration - this object is loaded and saved at startup/shutdown.
+
+### events variable
+The events object is used to add new event handlers to Minecraft.
+
+## Module variables
+The following variables are available only within the context of Modules. (not available at in-game prompt).
+
+### __filename variable
+The current file - this variable is only relevant from within the context of a Javascript module.
+
+### __dirname variable
+The current directory - this variable is only relevant from within the context of a Javascript module.
+
 ## Global functions
 
 ScripCraft provides some global functions which can be used by all plugins/modules...
 
 ### echo function
 
-The `echo()` function displays a message on the in-game screen. The message is displayed to the `self` player (this is usually the player who issued the `/js` or `/jsp` command).
+The `echo()` function displays a message on the in-game screen. The
+message is displayed to the `self` player (this is usually the player
+who issued the `/js` or `/jsp` command).
 
 ### Example
 
     /js echo('Hello World')
 
+For programmers familiar with Javascript web programming, an `alert`
+function is also provided.  `alert` works exactly the same as `echo`
+e.g. `alert('Hello World')`.
 
-* echo (message) - Displays a message on the screen. 
+### Notes
-   For example: `/js echo('Hello World')` will print Hello World on the in-game chat window.  
+
-   For programmers familiar with Javascript web programming, an `alert` function is also provided. 
+The `echo` and `alert` functions are provided as convenience functions
-   `alert` works exactly the same as `echo` e.g. `alert('Hello World')`. 
+for beginning programmers. The use of these 2 functions is not
+recommended in event-handling code or multi-threaded code. In such
+cases, if you want to send a message to a given player then use the
+Bukkit API's [Player.sendMessage()][plsm] function instead.
+
+[plsm]: 
 
  * require (modulename) - Will load modules. See [Node.js modules][njsmod]
 
- * load (filename,warnOnFileNotFound) - loads and evaluates a javascript file, returning the evaluated object. (Note: Prefer `require()` to `load()`)
+ * load (filename,warnOnFileNotFound) - loads and evaluates a
+   javascript file, returning the evaluated object. (Note: Prefer
+   `require()` to `load()`)
   
  * save (object, filename) - saves an object to a file.
 
@@ -166,8 +205,9 @@ The `echo()` function displays a message on the in-game screen. The message is d
 
 ### require() function
 
-ScriptCraft's `require()` function is used to load modules. The `require()` function takes a 
+ScriptCraft's `require()` function is used to load modules. The
-module name as a parameter and will try to load the named module.
+`require()` function takes a module name as a parameter and will try
+to load the named module.
 
 #### Parameters
 
@@ -260,7 +300,8 @@ persist data.
  
  * pluginName (String) : The name of the plugin - this becomes a global variable.
  * pluginDefinition (Object) : The various functions and members of the plugin object.
- * isPersistent (boolean - optional) : Specifies whether or not the plugin/object state should be loaded and saved by ScriptCraft.
+ * isPersistent (boolean - optional) : Specifies whether or not the
+   plugin/object state should be loaded and saved by ScriptCraft.
 
 #### Example
 
@@ -292,34 +333,90 @@ plugin author) safely expose javascript functions for use by players.
 
 #### Example
 
-See chat/colors.js or alias/alias.js or homes/homes.js for examples of how to use the `command()` function.
+See chat/colors.js or alias/alias.js or homes/homes.js for examples of
+how to use the `command()` function.
+
+### setTimeout() function
+
+This function mimics the setTimeout() function used in browser-based
+javascript.  However, the function will only accept a function
+reference, not a string of javascript code.  Where setTimeout() in the
+browser returns a numeric value which can be subsequently passed to
+clearTimeout(), This implementation returns a [BukkitTask][btdoc]
+object which can be subsequently passed to ScriptCraft's own
+clearTimeout() implementation.
+
+If Node.js supports setTimeout() then it's probably good for ScriptCraft to support it too.
+
+[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
+
+#### Example
+
+    //
+    // start a storm in 5 seconds
+    //    
+    setTimeout( function() {
+        var world = server.worlds.get(0);
+        world.setStorm(true);
+    }, 5000);
+
+### clearTimeout() function
+
+A scriptcraft implementation of clearTimeout().
+
+### setInterval() function
+
+This function mimics the setInterval() function used in browser-based
+javascript.  However, the function will only accept a function
+reference, not a string of javascript code.  Where setInterval() in
+the browser returns a numeric value which can be subsequently passed
+to clearInterval(), This implementation returns a [BukkitTask][btdoc]
+object which can be subsequently passed to ScriptCraft's own
+clearInterval() implementation.
+
+If Node.js supports setInterval() then it's probably good for
+ScriptCraft to support it too.
+
+[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
+
+### clearInterval() function
+
+A scriptcraft implementation of clearInterval().
+
+### refresh() function
+
+The refresh() function will ...
+
+1. Disable the ScriptCraft plugin.
+2. Unload all event listeners associated with the ScriptCraft plugin.
+3. Enable the ScriptCraft plugin.
+
+... refresh() can be used during development to reload only scriptcraft javascript files.
+See [issue #69][issue69] for more information.
+
+[issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
+
+### addUnloadHandler() function
+
+The addUnloadHandler() function takes a callback function as a
+parameter. The callback will be called when the ScriptCraft plugin is
+unloaded (usually as a result of a a `reload` command or server
+shutdown).
 
 ***/
 
-
-
-/*************************************************************************
-## global variables
-
-There are a couple of special javascript variables available in ScriptCraft...
- 
- * __folder - The current working directory - this variable is only to be used within the main body of a .js file.
- * __plugin - The ScriptCraft JavaPlugin object.
- * 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)
-
-***/
 /*
   wph 20130124 - make self, plugin and server public - these are far more useful now that tab-complete works.
 */
+var global = this;
 var server = org.bukkit.Bukkit.server;
-//
+/*
-// private implementation
+  private implementation
-//
+*/
 (function(){
-    //
+    /*
-    // don't execute this more than once
+      don't execute this more than once
-    //
+    */
     if (typeof load == "function")
         return ;
     var File = java.io.File;
@@ -333,8 +430,6 @@ var server = org.bukkit.Bukkit.server;
     var jsPluginsRootDir = parentFileObj.getParentFile();
     var jsPluginsRootDirName = _canonize(jsPluginsRootDir);
 
-
-
     var _loaded = {};
     /*
       Load the contents of the file and evaluate as javascript
@@ -351,9 +446,9 @@ var server = org.bukkit.Bukkit.server;
             file = new File(filename);
 
         var canonizedFilename = _canonize(file);
-        //
+        /*
-        // wph 20130123 don't load the same file more than once.
+          wph 20130123 don't load the same file more than once.
-        //
+        */
         if (_loaded[canonizedFilename])
             return _loaded[canonizedFilename];
         
@@ -399,8 +494,6 @@ var server = org.bukkit.Bukkit.server;
     if (!config)
         config = {verbose: false};
     global.config = config;
-
-
     /*
       Unload Handlers
     */
@@ -414,94 +507,27 @@ var server = org.bukkit.Bukkit.server;
         }
     };
 
-/*************************************************************************
-## Miscellaneous Core Functions
-
-### setTimeout() function
-
-This function mimics the setTimeout() function used in browser-based javascript.
-However, the function will only accept a function reference, not a string of javascript code.
-Where setTimeout() in the browser returns a numeric value which can be subsequently passed to 
-clearTimeout(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearTimeout() implementation.
-
-If Node.js supports setTimeout() then it's probably good for ScriptCraft to support it too.
-
-[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
-
-#### Example
-
-    //
-    // start a storm in 5 seconds
-    //    
-    setTimeout( function() {
-        var world = server.worlds.get(0);
-        world.setStorm(true);
-    }, 5000);
-
-***/
     global.setTimeout = function( callback, delayInMillis){
-        //
+        /*
-        // javascript programmers familiar with setTimeout know that it expects
+          javascript programmers familiar with setTimeout know that it expects
-        // a delay in milliseconds. However, bukkit's scheduler expects a delay in ticks 
+          a delay in milliseconds. However, bukkit's scheduler expects a delay in ticks 
-        // (where 1 tick = 1/20th second)
+          (where 1 tick = 1/20th second)
-        //
+        */
         var bukkitTask = server.scheduler.runTaskLater(__plugin, callback, delayInMillis/50);
         return bukkitTask;
     };
-    
-/*************************************************************************
-### clearTimeout() function
-
-A scriptcraft implementation of clearTimeout().
-
-***/
     global.clearTimeout = function(bukkitTask){
         bukkitTask.cancel();
     };
 
-/*************************************************************************
-### setInterval() function
-
-This function mimics the setInterval() function used in browser-based javascript.
-However, the function will only accept a function reference, not a string of javascript code.
-Where setInterval() in the browser returns a numeric value which can be subsequently passed to 
-clearInterval(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearInterval() implementation.
-
-If Node.js supports setInterval() then it's probably good for ScriptCraft to support it too.
-
-[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
-
-***/
     global.setInterval = function(callback, intervalInMillis){
         var delay = intervalInMillis/ 50;
         var bukkitTask = server.scheduler.runTaskTimer(__plugin, callback, delay, delay);
         return bukkitTask;
     };
-/*************************************************************************
-### clearInterval() function
-
-A scriptcraft implementation of clearInterval().
-
-***/
     global.clearInterval = function(bukkitTask){
         bukkitTask.cancel();
     };
-
-/*************************************************************************
-### refresh() function
-
-The refresh() function will ...
-
-1. Disable the ScriptCraft plugin.
-2. Unload all event listeners associated with the ScriptCraft plugin.
-3. Enable the ScriptCraft plugin.
-
-... refresh() can be used during development to reload only scriptcraft javascript files.
-See [issue #69][issue69] for more information.
-
-[issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
-
-***/
     global.refresh = function(){
         __plugin.pluginLoader.disablePlugin(__plugin);
         __plugin.pluginLoader.enablePlugin(__plugin);
@@ -518,7 +544,6 @@ See [issue #69][issue69] for more information.
     global.echo = _echo;
     global.alert = _echo;
     global.load = _load;
-    global.logger = __plugin.logger;
     
     global.addUnloadHandler = _addUnloadHandler;
 
@@ -530,13 +555,13 @@ See [issue #69][issue69] for more information.
                        jsPluginsRootDirName + '/modules/'];
     global.require = fnRequire(__plugin.logger, __engine, config.verbose, jsPluginsRootDirName, modulePaths);
 
+    global.console = require('console');
     var plugins = require('plugin');
     global._onTabComplete = require('tabcomplete');
 
     global.plugin = plugins.plugin;
     global.command = plugins.command;
     global.save = plugins.save;
-    global.console = require('console');
 
     var events = require('events');
     events.on('server.PluginDisableEvent',function(l,e){
@@ -551,6 +576,3 @@ See [issue #69][issue69] for more information.
 
     plugins.autoload(jsPluginsRootDir);
 }());
-
-
-

src/main/javascript/plugins/alias/alias.js

@@ -135,7 +135,7 @@ var _list = function(player){
             player.sendMessage(alias + " = " + JSON.stringify(_store.global[alias]) );
         }
     }catch(e){
-        logger.severe("Error in list function: " + e.message);
+        console.error("Error in list function: " + e.message);
         throw e;
     }
 };
@@ -173,7 +173,7 @@ var _intercept = function( msg, invoker, exec)
         isAlias = true;
     }else{
         if (config.verbose){
-            logger.info("No global alias found for command: " + command);
+            console.info("No global alias found for command: " + command);
         }
     }
     /*
@@ -186,7 +186,7 @@ var _intercept = function( msg, invoker, exec)
         isAlias = true;
     }else{
         if (config.verbose){
-            logger.info("No player alias found for command: " + command);
+            console.info("No player alias found for command: " + command);
         }
     }
     for (var i = 0;i < template.length; i++)

src/main/javascript/plugins/homes/homes.js

@@ -1,15 +1,71 @@
+/*************************************************************************
+## homes Module
+
+The homes plugin lets players set a location as home and return to the
+location, invite other players to their home and also visit other
+player's homes.
+
+This module is a good example of how to create a javascript-based
+minecraft mod which provides...
+
+ * A programmatic interface (API) and 
+ * A command extension which uses that API to provide new functionality for players.
+
+The module uses the `plugin()` function to specify an object and
+methods, and the `command()` function to expose functionality to
+players through a new `jsp home` command. This module also
+demonstrates how to enable autocompletion for custom commands (to see
+this in action, at the in-game prompt or server console prompt type
+`jsp home ` then press the TAB key - you should see a list of further
+possible options).
+
+The `jsp home` command has the following options...
+
+### Basic options
+
+ * `/jsp home set` Will set your current location as your
+   'home' location to which you can return at any time using the ...
+
+ * `/jsp home` ..command will return you to your home, if you have set one.
+
+ * `/jsp home <player>` Will take you to the home of <player> (where 
+   <player> is the name of the player whose home you wish to visit.
+
+ * `/jsp home delete` Deletes your home location from the location
+   database. This does not actually remove the home from the world or
+   change the world in any way. This command is completely
+   non-destructive and cannot be used for griefing. No blocks will be
+   destroyed by this command.
+
+### Social options
+The following options allow players to open their homes to all or some
+players, invite players to their home and see a list of homes they can
+visit.
+
+ * `/jsp home list` Lists home which you can visit.
+ * `/jsp home ilist` Lists players who can visit your home.
+ * `/jsp home invite <player>` Invites the named player to your home.
+ * `/jsp home uninvite <player>` Uninvites (revokes invitation) the named player to your home.
+ * `/jsp home public` Opens your home to all players (all players can visit your home).
+ * `/jsp home private` Makes your home private (no longer visitable by all).
+
+### Administration options
+The following administration options can only be used by server operators...
+
+ * `/jsp home listall` List all of the homes
+ * `/jsp home clear <player>` Removes the player's home
+   location. Again, this command does not destroy any structures in
+   the world, it simply removes the location from the database. No
+   blocks are destroyed by this command.
+
+***/
 var utils = require('utils');
-/*
-  TODO: Document this plugin!
-*/
 var _store = {
     houses: {},
     openHouses: {},
     invites: {}
 };
 /*
-  The homes plugin lets players set a location as home and return to the location, invite
-  other players to their home and also visit other player's homes.
 */
 var homes =  plugin("homes", { 
     help: function(){

src/main/javascript/plugins/minigames/NumberGuess.js

@@ -1,13 +1,13 @@
 /*************************************************************************
-# NumberGuess mini-game: 
+## NumberGuess mini-game: 
 
-## Description
+### 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
+### Example
     
     /js Game_NumberGuess.start()
 

src/main/javascript/plugins/minigames/SnowballFight.js

@@ -1,7 +1,7 @@
 /*************************************************************************
-# SnowballFight mini-game
+## SnowballFight mini-game
 
-## Description
+### Description
 
 This is a rough and ready prototype of a simple multi-player
 shoot-em-up. To start a game with all players playing against one another...