More docs

Author: tmcw

lib/infer/params.js

@@ -5,6 +5,24 @@ var shouldSkipInference = require('./should_skip_inference'),
   finders = require('./finders'),
   flowDoctrine = require('../flow_doctrine');
 
+/**
+ * Babel parses JavaScript source code and produces an abstract syntax
+ * tree that includes methods and their arguments. This function takes
+ * that AST and uses it to infer details that would otherwise need
+ * explicit documentation, like the names of comments and their
+ * default values.
+ *
+ * It is especially careful to allow the user and the machine to collaborate:
+ * documentation.js should not overwrite any details that the user
+ * explicitly sets.
+ *
+ * @private
+ * @param {Object} param the abstract syntax tree of the parameter in JavaScript
+ * @param {Object} comment the full comment object
+ * @param {number} i the number of this parameter, in argument order
+ * @param {string} prefix of the comment, if it is nested, like in the case of destructuring
+ * @returns {Object} parameter with inference.
+ */
 function paramToDoc(param, comment, i, prefix) {
 
   prefix = prefix || '';

lib/input/expand_directories.js

@@ -2,6 +2,17 @@ var fs = require('fs');
 var path = require('path');
 var _ = require('lodash');
 
+/**
+ * Given a list of indexes, expand those indexes that are paths
+ * to directories into sub-lists of files. This does _not_ work
+ * recursively and will throw an error if an index is not found
+ *
+ * @private
+ * @throws {Error} if index is not found
+ * @param {Array<Object|string>} indexes entry points given to documentatino
+ * @param {Function} filterer method that avoids evaluating non-JavaScript files
+ * @returns {Array<Object|string>} flattened array of file sources
+ */
 function expandDirectories(indexes, filterer) {
   return _.flatMap(indexes, function (index) {
     if (typeof index !== 'string') {