more documentation improvements

Author: tmcw

lib/flow_doctrine.js

@@ -17,6 +17,17 @@ var literalTypes = {
   'BooleanLiteralTypeAnnotation': 'BooleanLiteral'
 };
 
+/**
+ * Babel parses Flow annotations in JavaScript into AST nodes. documentation.js uses
+ * Babel to parse JavaScript. This method restructures those Babel-generated
+ * objects into objects that fit the output of Doctrine, the module we use
+ * to parse JSDoc annotations. This lets us use Flow annotations _as_
+ * JSDoc annotations.
+ *
+ * @private
+ * @param {Object} type babel-parsed flow type
+ * @returns {Object} doctrine compatible type
+ */
 function flowDoctrine(type) {
 
   if (type.type in namedTypes) {

lib/inline_tokenizer.js

@@ -1,5 +1,15 @@
 'use strict';
 
+/**
+ * Create a tokenizer method for Remark, our Markdown processor,
+ * that is able to parse JSDoc inline tokens
+ *
+ * @private
+ * @param {string} type the destination type of the parsed objects
+ * @param {RegExp} regex regular expression for extracting content
+ * from text
+ * @returns {Function} tokenizer
+ */
 function makeTokenizer(type, regex) {
   var tokenizer = function (eat, value, silent) {
     var match = regex.exec(value);

lib/server.js

@@ -100,6 +100,12 @@ Server.prototype.stop = function (callback) {
   }.bind(this));
 };
 
+/**
+ * A placeholder method that will be called instead of `callback` if
+ * callback is omitted for the server control methods
+ * @private
+ * @returns {undefined} doesn't return anything
+ */
 function noop() {}
 
 module.exports = Server;