Improve internal documentation

tmcw · tmcw · commit 7f032d6c6a85 · 2016-06-02T13:22:06.000-04:00
diff --git a/lib/hierarchy.js b/lib/hierarchy.js
@@ -2,13 +2,20 @@
 
 var hasOwnProperty = Object.prototype.hasOwnProperty;
 
-function pick(n) {
+/**
+ * Pick only relevant properties from a comment to store them in
+ * an inheritance chain
+ * @param {Object} comment
+ * @returns {Object} reduced comment
+ * @private
+ */
+function pick(comment) {
   var item = {
-    name: n.name,
-    kind: n.kind
+    name: comment.name,
+    kind: comment.kind
   };
-  if (n.scope) {
-    item.scope = n.scope;
+  if (comment.scope) {
+    item.scope = comment.scope;
   }
   return item;
 }
diff --git a/lib/parse.js b/lib/parse.js
@@ -1,12 +1,8 @@
 'use strict';
 
 var doctrine = require('doctrine');
-var remark = require('remark');
-var inlineTokenizer = require('./inline_tokenizer');
 
-function parseMarkdown(string) {
-  return remark.use(inlineTokenizer).parse(string);
-}
+var parseMarkdown = require('./parse_markdown');
 
 var flatteners = {
   'abstract': flattenBoolean,
@@ -317,6 +313,15 @@ function flattenMarkdownDescription(result, tag, key) {
   result[key] = parseMarkdown(tag.description);
 }
 
+/**
+ * Parse [kind shorthand](http://usejsdoc.org/tags-kind.html) into
+ * both name and type tags, like `@class [<type> <name>]`
+ *
+ * @param {Object} result comment
+ * @param {Object} tag parsed tag
+ * @param {string} key tag
+ * @private
+ */
 function flattenKindShorthand(result, tag, key) {
   result.kind = key;
 
diff --git a/lib/parse_markdown.js b/lib/parse_markdown.js
@@ -0,0 +1,16 @@
+var remark = require('remark');
+var inlineTokenizer = require('./inline_tokenizer');
+
+/**
+ * Parse a string of Markdown into a Remark
+ * abstract syntax tree.
+ *
+ * @param {string} string markdown text
+ * @returns {Object} abstract syntax tree
+ * @private
+ */
+function parseMarkdown(string) {
+  return remark.use(inlineTokenizer).parse(string);
+}
+
+module.exports = parseMarkdown;
diff --git a/lib/parsers/javascript.js b/lib/parsers/javascript.js
@@ -6,6 +6,14 @@ var babylon = require('babylon'),
   isJSDocComment = require('../../lib/is_jsdoc_comment'),
   parse = require('../../lib/parse');
 
+/**
+ * Left-pad a string so that it can be sorted lexicographically. We sort
+ * comments to keep them in order.
+ * @param {string} str the string
+ * @param {number} width the width to pad to
+ * @returns {string} a padded string with the correct width
+ * @private
+ */
 function leftPad(str, width) {
   str = str.toString();
   while (str.length < width) {
@@ -46,8 +54,24 @@ function parseJavaScript(data) {
 
   var visited = {};
 
+  /**
+   * Iterate through the abstract syntax tree, finding a different kind of comment
+   * each time, and optionally including context. This is how we find
+   * JSDoc annotations that will become part of documentation
+   * @param {Object} ast the babel-parsed syntax tree
+   * @param {string} type comment type to find
+   * @param {boolean} includeContext to include context in the nodes
+   * @returns {Array<Object>} comments
+   * @private
+   */
   function walkComments(ast, type, includeContext) {
     traverse(ast, {
+      /**
+       * Process a parse in an abstract syntax tree
+       * @param {Object} path ast path
+       * @returns {undefined} causes side effects
+       * @private
+       */
       enter: function (path) {
         /**
          * Parse a comment with doctrine and decorate the result with file position and code context.
diff --git a/lib/sort.js b/lib/sort.js
@@ -1,11 +1,6 @@
 'use strict';
 
-var remark = require('remark');
-var inlineTokenizer = require('./inline_tokenizer');
-
-function parseMarkdown(string) {
-  return remark.use(inlineTokenizer).parse(string);
-}
+var parseMarkdown = require('./parse_markdown');
 
 /**
  * Sort two documentation objects, given an optional order object. Returns
