Improve internal documentation

Author: tmcw

README.md

@@ -5,6 +5,7 @@
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/documentationjs/documentation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 [![David](https://david-dm.org/documentationjs/documentation.svg)](https://david-dm.org/documentationjs/documentation)
 [![codecov.io](https://codecov.io/github/documentationjs/documentation/coverage.svg?branch=master)](https://codecov.io/github/documentationjs/documentation?branch=master)
+[![Inline docs](http://inch-ci.org/github/documentationjs/documentation.svg?branch=master&style=flat-square)](http://inch-ci.org/github/documentationjs/documentation)
 
 A **documentation generation system** that's
 _beautiful_ by default, _flexible_ across formats and styles, and

lib/commands/readme.js

@@ -36,6 +36,13 @@ module.exports.parseArgs = function (yargs) {
   .example('documentation readme index.js -s "API Docs" --github');
 };
 
+/**
+ * Insert API documentation into a Markdown readme
+ * @private
+ * @param {Object} documentation the module instance
+ * @param {Object} parsedArgs args from the CLI option parser
+ * @return {undefined} has the side-effect of writing a file or printing to stdout
+ */
 function readme(documentation, parsedArgs) {
   var readmeOptions = parsedArgs.commandOptions;
   readmeOptions.format = 'remark';

lib/lint.js

@@ -55,6 +55,12 @@ function lintComments(comment) {
   return comment;
 }
 
+/**
+ * @private
+ * Extract lint instructions from comments and generate user-readable output.
+ * @param {Array<Object>} comments a list of comments
+ * @return {string} user-readable output
+ */
 function formatLint(comments) {
   var vFiles = {};
   walk(comments, function (comment) {

lib/nest.js

@@ -1,5 +1,15 @@
 'use strict';
 
+/**
+ * Nest nestable tags, like param and property, into nested
+ * arrays that are suitable for output.
+ *
+ * @private
+ * @param {Object} comment a comment with tags
+ * @param {string} tagName the tag to nest
+ * @param {string} target the tag to nest into
+ * @returns {Object} nested comment
+ */
 function nestTag(comment, tagName, target) {
   if (!comment[target]) {
     return comment;

lib/parse.js

@@ -256,24 +256,63 @@ var flatteners = {
 
 function todo() {}
 
+/**
+ * Generate a function that curries a destination key for a flattener
+ * @private
+ * @param {string} key the eventual destination key
+ * @returns {Function} a flattener that remembers that key
+ */
 function synonym(key) {
   return function (result, tag) {
     return flatteners[key](result, tag, key);
   };
 }
 
+/**
+ * Treat the existence of a tag as a sign to mark `key` as true in the result
+ * @private
+ * @param {Object} result the documentation object
+ * @param {Object} tag the tag object, with a name property
+ * @param {string} key destination on the result
+ * @returns {undefined} operates with side-effects
+ */
 function flattenBoolean(result, tag, key) {
   result[key] = true;
 }
 
+/**
+ * Flatten a usable-once name tag into a key
+ * @private
+ * @param {Object} result the documentation object
+ * @param {Object} tag the tag object, with a name property
+ * @param {string} key destination on the result
+ * @returns {undefined} operates with side-effects
+ */
 function flattenName(result, tag, key) {
   result[key] = tag.name;
 }
 
+
+/**
+ * Flatten a usable-once description tag into a key
+ * @private
+ * @param {Object} result the documentation object
+ * @param {Object} tag the tag object, with a description property
+ * @param {string} key destination on the result
+ * @returns {undefined} operates with side-effects
+ */
 function flattenDescription(result, tag, key) {
   result[key] = tag.description;
 }
 
+/**
+ * Flatten a usable-once description tag into a key and parse it as Markdown
+ * @private
+ * @param {Object} result the documentation object
+ * @param {Object} tag the tag object, with a description property
+ * @param {string} key destination on the result
+ * @returns {undefined} operates with side-effects
+ */
 function flattenMarkdownDescription(result, tag, key) {
   result[key] = parseMarkdown(tag.description);
 }