Improve internal documentation

tmcw · tmcw · commit e25919b0d4e2 · 2016-06-02T12:40:06.000-04:00
diff --git a/lib/infer/finders.js b/lib/infer/finders.js
@@ -1,5 +1,13 @@
 var t = require('babel-types');
 
+/**
+ * Try to find the part of JavaScript a comment is referring to, by
+ * looking at the syntax tree closest to that comment.
+ *
+ * @param {Object} path abstract syntax tree path
+ * @returns {?Object} ast node, if one is found.
+ * @private
+ */
 function findTarget(path) {
 
   if (!path) {
@@ -27,6 +35,14 @@ function findTarget(path) {
   return path;
 }
 
+/**
+ * Try to find a JavaScript class that this comment refers to,
+ * whether an expression in an assignment, or a declaration.
+ *
+ * @param {Object} node abstract syntax tree node
+ * @returns {?Object} ast node, if one is found.
+ * @private
+ */
 function findClass(node) {
   var target = findTarget(node);
   return (t.isClassDeclaration(target) || t.isClassExpression(target)) && target;
diff --git a/lib/infer/membership.js b/lib/infer/membership.js
@@ -6,6 +6,15 @@ var n = require('babel-types'),
   isJSDocComment = require('../../lib/is_jsdoc_comment'),
   parse = require('../../lib/parse');
 
+/**
+ * Given an AST node, try to find a comment in front of it that
+ * has a `lends` tag, and if it has that, return the tag, split by
+ * .s.
+ *
+ * @private
+ * @param {Object} node AST node
+ * @returns {string|undefined} lends identifier, if any
+ */
 function findLendsIdentifiers(node) {
   if (!node || !node.leadingComments) {
     return;
@@ -44,6 +53,7 @@ function extractIdentifiers(path) {
 
 /**
  * Count leading identifiers that refer to a module export (`exports` or `module.exports`).
+ * @private
  * @param {Object} comment parsed comment
  * @param {Array<string>} identifiers array of identifier names
  * @returns {number} number of identifiers referring to a module export (0, 1 or 2)
@@ -65,6 +75,7 @@ function countModuleIdentifiers(comment, identifiers) {
  * tags from the placement of JSDoc
  * annotations within a file
  *
+ * @private
  * @param {Object} comment parsed comment
  * @returns {Object} comment with membership inferred
  */
