Test examples, add API docs. Fixes #2

Author: tmcw

README.md

@@ -5,3 +5,43 @@
 
 Utilities that help in the process of building theme modules
 for documentation.js.
+
+## API
+
+### link
+
+Helper used to automatically link items to global JS documentation or to internal
+documentation.
+
+**Parameters**
+
+-   `text` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** text to potentially link
+-   `getHref` **\[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** a function that tries
+    to find a URL to point a named link to
+-   `description`  
+
+**Examples**
+
+```javascript
+link('string').url // => 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String'
+```
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** [mdast](https://www.npmjs.com/package/mdast) node
+
+### formatType
+
+Helper used to format JSDoc-style type definitions into HTML or Markdown.
+
+**Parameters**
+
+-   `node` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** type object in doctrine style
+-   `getHref` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function that tries
+    to find a URL to point a named link to
+
+**Examples**
+
+```javascript
+formatType({ type: 'NameExpression', name: 'String' })[0].url // => 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String'
+```
+
+Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** array of [mdast](https://www.npmjs.com/package/mdast) syntax trees

index.js

@@ -14,6 +14,8 @@ function t(text) {
  * @param {function} [getHref] - a function that tries
  * to find a URL to point a named link to
  * @returns {Object} [mdast](https://www.npmjs.com/package/mdast) node
+ * @example
+ * link('string').url // => 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String'
  */
 function link(text, getHref, description) {
   var href = (getHref && getHref(text)) || globalsDocs.getDoc(text);
@@ -59,10 +61,7 @@ function decorate(formatted, str, prefix) {
  * to find a URL to point a named link to
  * @returns {Object[]} array of [mdast](https://www.npmjs.com/package/mdast) syntax trees
  * @example
- * var x = { type: 'NameExpression', name: 'String' };
- * // in template
- * // {{ type x }}
- * // generates String
+ * formatType({ type: 'NameExpression', name: 'String' })[0].url // => 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String'
  */
 function formatType(node, getHref) {
   var result = [];

package.json

@@ -4,7 +4,9 @@
   "description": "helpers for building themes with documentation.js",
   "main": "index.js",
   "scripts": {
-    "test": "tap --coverage test"
+    "test": "tap --coverage test && npm run jsdoctest",
+    "jsdoctest": "mocha --require jsdoctest index.js",
+    "doc": "documentation readme index.js --section=API"
   },
   "keywords": [
     "documentation",
@@ -20,6 +22,9 @@
     "unist-builder": "^1.0.0"
   },
   "devDependencies": {
+    "documentation": "4.0.0-beta4",
+    "jsdoctest": "1.6.0",
+    "mocha": "2.5.3",
     "remark": "^4.1.2",
     "tap": "^5.7.0"
   }