Update API Docs (#47)

Carol Hansen · web-flow · commit 7b7e67854fb2 · 2017-06-16T15:22:09.000-05:00
Update API docs
diff --git a/API.md b/API.md
@@ -1,4 +1,14 @@
-# HelloWorld
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+-   [HelloWorld](#helloworld)
+    -   [shout](#shout)
+    -   [wave](#wave)
+-   [hello_async](#hello_async)
+-   [hello](#hello)
+
+## HelloWorld
 
 Main class, called HelloWorld
 
@@ -7,9 +17,32 @@ Main class, called HelloWorld
 ```javascript
 var HelloWorld = require('index.js');
 var HW = new HelloWorld();
+         OR
+var HW = new HelloWorld('yo');
+```
+
+### shout
+
+Shout a phrase really loudly by adding an exclamation to the end, asynchronously
+
+**Parameters**
+
+-   `string` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** phrase to shout
+-   `args` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** different ways to shout
+    -   `args.louder` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** adds exclamation points to the string
+-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** from whence the shout comes, returns a string
+
+**Examples**
+
+```javascript
+var HW = new HelloWorld();
+HW.shout('rawr', { louder: true }, function(err, shout) {
+  if (err) throw err;
+  console.log(shout); // => 'rawr!'
+});
 ```
 
-## wave
+### wave
 
 Say howdy to the world
 
@@ -22,22 +55,38 @@ console.log(wave); // => 'howdy world!'
 
 Returns **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a happy-go-lucky string saying hi
 
-## shout
+## hello_async
 
-Shout a phrase really loudly by adding an exclamation to the end, asynchronously
+This is a standalone function (async) that logs a string.
 
 **Parameters**
 
--   `phrase` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** to shout
--   `different` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** ways to shout
--   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** from whence the shout comes, returns a string
+-   `args` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** different ways to alter the string
+    -   `args.louder` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** adds exclamation points to the string
+-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** from whence the hello comes, returns a string
 
 **Examples**
 
 ```javascript
-var HW = new HelloWorld();
-HW.shout('rawr', {}, function(err, shout) {
+var module = require('./path/to/lib/index.js');
+module.hello_async({ louder: true }, function(err, result) {
   if (err) throw err;
-  console.log(shout); // => 'rawr!'
+  console.log(result); // => "...threads are busy async bees...world!!!!"
 });
 ```
+
+Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** an ever-so-slightly customizable string
+
+## hello
+
+This is a standalone function (sync) that logs a string.
+
+**Examples**
+
+```javascript
+var module = require('./path/to/lib/index.js');
+var check = module.hello();
+console.log(check); // => "world"
+```
+
+Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** "world"
diff --git a/README.md b/README.md
@@ -37,6 +37,11 @@ make clean
 # This is useful if you want to nuke everything and start from scratch.
 # For example, it's super useful for making sure everything works for Travis, production, someone else's machine, etc
 make disclean
+
+# This skel uses documentation.js to auto-generate API docs.
+# If you'd like to generate docs for your code, you'll need to install documentation.js,
+# and then add your subdirectory to the docs command in package.json
+npm install -g documentation
 ```
 
 Note: by default the build errors on compiler warnings. To disable this do:
@@ -80,7 +85,8 @@ var module = require('./path/to/lib/index.js');
 
 module.hello_async({ louder: true }, function(err, result) {
   if (err) throw err;
-  console.log(hi); // => ...threads are busy async bees...world!!!!
+
+  console.log(result); // => "...threads are busy async bees...world!!!!""
 });
 ```
 
diff --git a/package.json b/package.json
@@ -12,7 +12,7 @@
     "test": "tape test/*.test.js",
     "prepublish": "npm ls",
     "install": "node-pre-gyp install --fallback-to-build",
-    "docs": "npm install ^4.0.0-beta5 && documentation build src/*.cpp --polyglot -f md -o API.md"
+    "docs": "documentation build src/*.cpp src/standalone_async/*.cpp src/standalone/*.cpp --polyglot -f md -o API.md"
   },
   "author": "Mapbox",
   "license": "ISC",
diff --git a/src/hello_world.cpp b/src/hello_world.cpp
@@ -104,12 +104,13 @@ NAN_METHOD(HelloWorld::wave)
  *
  * @name shout
  * @memberof HelloWorld
- * @param {String} phrase to shout
- * @param {Object} different ways to shout
+ * @param {String} string - phrase to shout
+ * @param {Object} args - different ways to shout
+ * @param {boolean} args.louder - adds exclamation points to the string
  * @param {Function} callback - from whence the shout comes, returns a string
  * @example
  * var HW = new HelloWorld();
- * HW.shout('rawr', {}, function(err, shout) {
+ * HW.shout('rawr', { louder: true }, function(err, shout) {
  *   if (err) throw err;
  *   console.log(shout); // => 'rawr!'
  * });
diff --git a/src/standalone/hello.cpp b/src/standalone/hello.cpp
@@ -1,5 +1,14 @@
 #include "hello.hpp"
 
+/**
+ * This is a standalone function (sync) that logs a string.
+ * @name hello
+ * @returns {string} "world"
+ * @example
+ * var module = require('./path/to/lib/index.js');
+ * var check = module.hello();
+ * console.log(check); // => "world"
+ */
 namespace standalone {
 
   // hello is a "standalone function" because it's not a class.
diff --git a/src/standalone_async/hello_async.cpp b/src/standalone_async/hello_async.cpp
@@ -5,6 +5,20 @@
 #include <iostream>
 #include <map>
 
+/**
+ * This is a standalone function (async) that logs a string.
+ * @name hello_async
+ * @param {Object} args - different ways to alter the string
+ * @param {boolean} args.louder - adds exclamation points to the string
+ * @param {Function} callback - from whence the hello comes, returns a string
+ * @returns {string} an ever-so-slightly customizable string
+ * @example
+ * var module = require('./path/to/lib/index.js');
+ * module.hello_async({ louder: true }, function(err, result) {
+ *   if (err) throw err;
+ *   console.log(result); // => "...threads are busy async bees...world!!!!"
+ * });
+ */
 namespace standalone_async {
 
   /*
