Improve internal documentation

Author: tmcw

lib/git/url_prefix.js

@@ -3,6 +3,14 @@ var path = require('path');
 var urlFromGit = require('github-url-from-git');
 var getRemoteOrigin = require('remote-origin-url');
 
+/**
+ * Given a a root directory, find its git configuration and figure out
+ * the HTTPS URL at the base of that GitHub repository.
+ *
+ * @param {string} root path at the base of this local repo
+ * @returns {string} base HTTPS url of the GitHub repository
+ * @throws {Error} if the root is not a git repo
+ */
 function getGithubURLPrefix(root) {
   return urlFromGit(getRemoteOrigin.sync(root)) + '/blob/' +
     fs.readFileSync(path.join(root, '.git',

lib/output/markdown_ast.js

@@ -7,7 +7,25 @@ function identity(x) {
   return x;
 }
 
+/**
+ * Given a hierarchy-nested set of comments, generate an mdast-compatible
+ * Abstract Syntax Usable for generating Markdown output
+ *
+ * @param {Array<Object>} comments nested comment
+ * @param {Object} opts currently none accepted
+ * @param {Function} callback called with AST
+ * @returns {undefined} calls callback
+ */
 function commentsToAST(comments, opts, callback) {
+
+  /**
+   * Generate an AST chunk for a comment at a given depth: this is
+   * split from the main function to handle hierarchially nested comments
+   *
+   * @param {number} depth nesting of the comment, starting at 1
+   * @param {Object} comment a single comment
+   * @returns {Object} mdast-compatible AST
+   */
   function generate(depth, comment) {
 
     function paramList(params) {

lib/walk.js

@@ -1,3 +1,11 @@
+/**
+ * Apply a function to all comments within a hierarchy: this iterates
+ * through children in the 'members' property.
+ *
+ * @param {Array<Object>} comments an array of nested comments
+ * @param {Function} fn a walker function
+ * @returns {undefined} calls fn
+ */
 function walk(comments, fn) {
   return comments.map(function (comment) {
     comment.members.instance = walk(comment.members.instance, fn);

test/bin.js

@@ -16,6 +16,8 @@ function documentation(args, options, callback, parseJSON) {
     options.cwd = __dirname;
   }
 
+  options.maxBuffer = 1024 * 1024;
+
   args.unshift(path.join(__dirname, '../bin/documentation.js'));
 
   exec(args.join(' '), options, function (err, stdout, stderr) {