docs: update docs for using a plugin

Author: nfischer

README.md

@@ -58,3 +58,10 @@ shell.open('file.txt'); // the plugin is now available!
  - Windows
 
 This is only supported for Node v4+
+
+## Writing plugins
+
+If you're interested in taking a look at the current state of the plugin API,
+take a look at [index.js](index.js). This has helpful comments explaining the
+necessary boilerplate for writing a plugin. For an example usage of the plugin,
+take a look at [test/test.js](test/test.js).

index.js

@@ -1,19 +1,16 @@
+// This exposes the plugin utilities
 var plugin = require('shelljs/src/common');
+
+// Require whatever modules you need for your project
 var child = require('child_process');
 var shell = require('shelljs');
 var fs = require('fs');
 
-//@
-//@ ### open([options,] file [, file ...])
-//@ ### open([options,] file_array)
-//@ Examples:
-//@
-//@ ```javascript
-//@ open('file.jpg');
-//@ ```
-//@
-//@ Opens files with their default application
+// Implement your command in a function, which takes an options string as the
+// first parameter
 function open(options, fileName) {
+  // Use the plugin utils to parse the options to only those options that are
+  // available (in this case, there are no available options
   options = plugin.parseOptions(options, {
   });
 
@@ -36,6 +33,8 @@ function open(options, fileName) {
   return new shell.ShellString('', '', 0);
 }
 
+// Register the new plugin as a ShellJS command
 plugin.register('open', open, { globStart: 1 });
 
+// Optionally, you can export the implementation of the command like so:
 exports.open = open;

test/test.js

@@ -1,6 +1,17 @@
-/* globals describe, it, before, afterEach */
+/* globals describe, it */
+
+// Steps for using a plugin:
+// First, you must load in ShellJS:
 var shell = require('shelljs');
-var pluginOpen = require('..'); // load plugin
+// After that, you can load the plugin:
+var pluginOpen = require('..');
+/*
+ * You can load a plugin with either of the following syntaxes:
+ * `require('shelljs-plugin-open');` or
+ * `var pluginOpen = require('shelljs-plugin-open');`
+*/
+
+// Now, require whichever other modules you want to require:
 require('should');
 
 // override console.error() to cover up common.error() calls