Improve internal documentation, upgrade theme-default. Refs #115

Author: tmcw

lib/args.js

@@ -78,7 +78,7 @@ module.exports = function (args) {
 
   var inputs,
     name = argv.name,
-    version = argv.version,
+    version = argv['project-version'],
     transform;
 
   if (argv._.length > 0) {
@@ -88,7 +88,7 @@ module.exports = function (args) {
       var p = require(path.resolve('package.json'));
       inputs = [p.main || 'index.js'];
       name = name || p.name;
-      version = version || p['project-version'];
+      version = version || p.version;
       if (p.browserify && p.browserify.transform) {
         transform = p.browserify.transform;
       }

lib/filter_access.js

@@ -7,13 +7,12 @@ var walk = require('./walk');
  * users to write documentation for non-public members by using the
  * `@private` tag.
  *
- * @name access
  * @public
  * @param {Array<string>} [levels=['private']] excluded access levels.
  * @param {Array<Object>} comments parsed comments (can be nested)
  * @return {Array<Object>} filtered comments
  */
-module.exports = function (levels, comments) {
+function filterAccess(levels, comments) {
   levels = levels || ['private'];
 
   function filter(comment) {
@@ -27,4 +26,6 @@ module.exports = function (levels, comments) {
   }
 
   return walk(comments.filter(filter), recurse);
-};
+}
+
+module.exports = filterAccess;

lib/filter_js.js

@@ -5,11 +5,12 @@
  * with JSDoc or parsed with espree, so we filter them out before
  * they reach documentation's machinery.
  *
- * @name access
  * @public
  * @param {Object} data a file as an object with 'file' property
  * @return {boolean} whether the file is json
  */
-module.exports = function (data) {
+function filterJS(data) {
   return !data.file.match(/\.json$/);
-};
+}
+
+module.exports = filterJS;

lib/get_template.js

@@ -12,11 +12,13 @@ var path = require('path');
  * @param {string} name template name
  * @returns {Function} template function
  */
-module.exports = function getTemplate(Handlebars, themeModule, name) {
+function getTemplate(Handlebars, themeModule, name) {
   try {
     return Handlebars
       .compile(fs.readFileSync(path.join(themeModule, name), 'utf8'));
   } catch (e) {
     throw new Error('Template file ' + name + ' missing');
   }
-};
+}
+
+module.exports = getTemplate;

lib/html_helpers.js

@@ -1,22 +1,10 @@
 'use strict';
 
-var slugg = require('slugg'),
-  getGlobalExternalLink = require('globals-docs').getDoc,
+var getGlobalExternalLink = require('globals-docs').getDoc,
   mdast = require('mdast'),
   html = require('mdast-html'),
   inlineLex = require('jsdoc-inline-lex');
 
-/**
- * Make slugg a unary so we can use it in functions
- *
- * @private
- * @param {string} input text
- * @returns {string} output
- */
-function slug(input) {
-  return input ? slugg(input) : '';
-}
-
 /**
  * Format a description and target as a Markdown link.
  *
@@ -47,12 +35,12 @@ function formatInlineTags(text) {
     } else if (tokens[i].type === 'link') {
       var parts = tokens[i].capture[1].split(/\s|\|/);
       if (parts.length === 1) {
-        output += markdownLink(tokens[i].capture[1], slug(tokens[i].capture[1]));
+        output += markdownLink(tokens[i].capture[1], tokens[i].capture[1]);
       } else {
-        output += markdownLink(parts.slice(1).join(' '), slug(parts[0]));
+        output += markdownLink(parts.slice(1).join(' '), parts[0]);
       }
     } else if (tokens[i].type === 'prefixLink') {
-      output += markdownLink(tokens[i].capture[1], slug(tokens[i].capture[2]));
+      output += markdownLink(tokens[i].capture[1], tokens[i].capture[2]);
     }
   }
 
@@ -66,8 +54,8 @@ function formatInlineTags(text) {
  * @returns {string} potentially linked HTML
  */
 function autolink(paths, text) {
-  if (paths.indexOf(slug(text)) !== -1) {
-    return '<a href="#' + slug(text) + '">' + text + '</a>';
+  if (paths.indexOf(text) !== -1) {
+    return '<a href="#' + text + '">' + text + '</a>';
   } else if (getGlobalExternalLink(text)) {
     return '<a href="' + getGlobalExternalLink(text) + '">' + text + '</a>';
   }
@@ -147,9 +135,9 @@ function formatParameters() {
  * @param {Array<string>} paths list of valid namespace paths that are linkable
  * @returns {undefined} invokes side effects on Handlebars
  */
-module.exports = function (Handlebars, paths) {
+function htmlHelpers(Handlebars, paths) {
   Handlebars.registerHelper('permalink', function () {
-    return this.path.map(slug).join('/');
+    return this.path.join('.');
   });
 
   Handlebars.registerHelper('autolink', autolink.bind(autolink, paths));
@@ -176,4 +164,6 @@ module.exports = function (Handlebars, paths) {
   Handlebars.registerHelper('format_type', function (type) {
     return formatType(type, paths);
   });
-};
+}
+
+module.exports = htmlHelpers;

lib/output/html.js

@@ -5,24 +5,12 @@ var File = require('vinyl'),
   concat = require('concat-stream'),
   Handlebars = require('handlebars'),
   extend = require('extend'),
-  slugg = require('slugg'),
   walk = require('../walk'),
   getTemplate = require('../get_template'),
   resolveTheme = require('../resolve_theme'),
   helpers = require('../html_helpers'),
   hljs = require('highlight.js');
 
-/**
- * Make slugg a unary so we can use it in functions
- *
- * @private
- * @param {string} input text
- * @returns {string} output
- */
-function slug(input) {
-  return input ? slugg(input) : '';
-}
-
 /**
  * Given a string of JavaScript, return a string of HTML representing
  * that JavaScript highlighted.
@@ -70,11 +58,10 @@ module.exports = function makeHTML(comments, opts, callback) {
 
   var pageTemplate = getTemplate(Handlebars, themeModule, 'index.hbs');
   Handlebars.registerPartial('section',
-
-  getTemplate(Handlebars, themeModule, 'section.hbs'));
+    getTemplate(Handlebars, themeModule, 'section.hbs'));
 
   var paths = comments.map(function (comment) {
-    return comment.path.map(slug).join('/');
+    return comment.path.join('.');
   }).filter(function (path) {
     return path;
   });

lib/parse.js

@@ -15,7 +15,7 @@ var doctrine = require('doctrine'),
  * @return {Object} an object conforming to the
  * [documentation JSON API](https://github.com/documentationjs/api-json) schema
  */
-module.exports = function (comment, loc, context) {
+function parseJSDoc(comment, loc, context) {
   var result = doctrine.parse(comment, {
     // have doctrine itself remove the comment asterisks from content
     unwrap: true,
@@ -45,4 +45,6 @@ module.exports = function (comment, loc, context) {
   }
 
   return flatten(normalize(result));
-};
+}
+
+module.exports = parseJSDoc;

lib/parsers/javascript.js

@@ -6,38 +6,21 @@ var babel = require('babel-core'),
   isJSDocComment = require('../../lib/is_jsdoc_comment'),
   parse = require('../../lib/parse');
 
-/**
- * Comment-out a shebang line that may sit at the top of a file,
- * making it executable on linux-like systems.
- * @param {string} code the source code in full
- * @return {string} code
- * @example
- * var foo = commentShebang('#!/usr/bin/env/node');
- * foo === '//#!/usr/bin/env/node';
- */
-function commentShebang(code) {
-  return (code[0] === '#' && code[1] === '!') ? '//' + code : code;
-}
-
-var parseOpts = {
-  code: false,
-  stage: 0,
-  locations: true,
-  ranges: true
-};
-
 /**
  * Receives a module-dep item,
  * reads the file, parses the JavaScript, and parses the JSDoc.
  *
- * @name parse
  * @param {Object} data a chunk of data provided by module-deps
  * @return {Array<Object>} an array of parsed comments
  */
-module.exports = function (data) {
+function parseJavaScript(data) {
   var results = [];
-  var code = commentShebang(data.source),
-    ast = babel.parse(code, parseOpts);
+  var ast = babel.parse(data.source, {
+    code: false,
+    stage: 0,
+    locations: true,
+    ranges: true
+  });
 
   var visited = {};
 
@@ -69,8 +52,8 @@ module.exports = function (data) {
               });
 
               if (path.parent && path.parent.node) {
-                context.code = code.substring
-                  .apply(code, path.parent.node.range);
+                context.code = data.source.substring
+                  .apply(data.source, path.parent.node.range);
               }
             } else {
               // Avoid the invariant of a comment with no AST by providing
@@ -98,4 +81,6 @@ module.exports = function (data) {
   walkComments(ast, 'trailingComments', false);
 
   return results;
-};
+}
+
+module.exports = parseJavaScript;

lib/parsers/polyglot.js

@@ -9,11 +9,10 @@ var getComments = require('get-comments'),
  * Documentation stream parser: this receives a module-dep item,
  * reads the file, parses the JavaScript, parses the JSDoc, and
  * emits parsed comments.
- * @name parse
  * @param {Object} data a chunk of data provided by module-deps
  * @return {Array<Object>} adds to memo
  */
-module.exports = function (data) {
+function parsePolyglot(data) {
   return getComments(data.source, true)
     .filter(isJSDocComment)
     .map(function (comment) {
@@ -23,4 +22,6 @@ module.exports = function (data) {
       };
       return parse(comment.value, comment.loc, context);
     });
-};
+}
+
+module.exports = parsePolyglot;

package.json

@@ -21,7 +21,7 @@
     "brfs": "^1.4.0",
     "concat-stream": "^1.5.0",
     "doctrine": "^0.7.0",
-    "documentation-theme-default": "^1.0.0-alpha2",
+    "documentation-theme-default": "^1.0.0",
     "extend": "^3.0.0",
     "get-comments": "^1.0.1",
     "github-url-from-git": "^1.4.0",