feat(core): Switch to Promises everywhere. Adopt Node v4 ES6 (#648)

* feat(core): Switch to Promises everywhere. Adopt Node v4 ES6

Big changes:

* Uses template strings where appropriate
* Config and argument parsing is unified and there is no such thing
  as formatterOptions anymore. All user-passed options go through
  mergeConfig.
* The node API surface changed (again): `buildSync` is removed,
  building operations return Promises.
* Now using Flow for internal type annotations.

More changes:

* Remove buildSync command
* feat(inference): Partially implement object shorthand support
* Refs #649
* Use Flow annotations to  enforce types
* Keep flow but switch to comment syntax
* Clarify types
* More flow improvements
* Turn server into class
* LinkerStack becomes class too
* Fix comment description type
* Run flow on lint
* Many more flow fixes
* More intense flow refactoring
* Simplify inference steps
* Update inference tests, flow errors down to 1
* Continue refining types
* Fix more flow issues
* Use 'use strict' everywhere
* Make 'ast' property configurable
* Fix many tests
* Fix more tests
* Fix more tests
* Fix augments
* Test Markdown meta support
* Improve test coverage
* Switch back from for of to for for speed

Author: tmcw

.eslintrc

@@ -1,6 +1,12 @@
 {
   "root": true,
-  "parser": "espree",
+  "parser": "babel-eslint",
+  "parserOptions": {
+    "sourceType": "script"
+  },
+  "plugins": [
+    "flowtype"
+  ],
   "rules": {
     "space-in-parens": 2,
     "space-before-blocks": 2,
@@ -21,8 +27,8 @@
     "no-new": 2,
     "key-spacing": 2,
     "no-multi-spaces": 2,
-    "valid-jsdoc": 2,
     "brace-style": 2,
+    "object-shorthand": ["error", "always", { "avoidQuotes": true }],
     "no-throw-literal": 2,
     "no-self-compare": 2,
     "no-void": 2,
@@ -32,13 +38,15 @@
     "quotes": [2, "single"],
     "indent": [2, 2],
     "curly": 2,
+    "strict": [2, "global"],
     "no-shadow": 0,
-    "no-undef": 2
+    "no-undef": 2,
+    "flowtype/define-flow-type": 1,
+    "flowtype/use-flow-type": 1
   },
   "extends": "eslint:recommended",
   "env": {
     "node": true,
-    "es6": true,
-    "browser": true
+    "es6": true
   }
 }

.flowconfig

@@ -0,0 +1,12 @@
+[ignore]
+.*node_modules/.cache/.*
+.*node_modules/conventional-changelog-core/test/fixtures/.*
+.*/test/fixture/.*
+
+[include]
+
+[libs]
+declarations/
+
+[options]
+module.ignore_non_literal_requires=true

README.md

@@ -46,21 +46,21 @@ lets you run `documentation` as a [Gulp](http://gulpjs.com/) build task.
 
 ## Examples
 
-* [HTML output with default template](http://documentation.js.org/html-example/)
-* [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
-* [JSON](http://documentation.js.org/html-example/index.json)
+-   [HTML output with default template](http://documentation.js.org/html-example/)
+-   [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
+-   [JSON](http://documentation.js.org/html-example/index.json)
 
 ## Documentation
 
-* [Getting Started](docs/GETTING_STARTED.md): start here
-* [Usage](docs/USAGE.md): how to use documentation.js
-* [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
-* [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
-* [Configuring documentation.js](docs/CONFIG.md)
-* [FAQ](docs/FAQ.md)
-* [Troubleshooting](docs/TROUBLESHOOTING.md)
-* [Theming](docs/THEMING.md): tips for theming documentation output in HTML
-* [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
+-   [Getting Started](docs/GETTING_STARTED.md): start here
+-   [Usage](docs/USAGE.md): how to use documentation.js
+-   [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
+-   [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
+-   [Configuring documentation.js](docs/CONFIG.md)
+-   [FAQ](docs/FAQ.md)
+-   [Troubleshooting](docs/TROUBLESHOOTING.md)
+-   [Theming](docs/THEMING.md): tips for theming documentation output in HTML
+-   [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
 
 ## User Guide
 
@@ -116,9 +116,9 @@ _We have plenty of
 [issues](https://github.com/documentationjs/documentation/issues) that we'd
 love help with._
 
-* Robust and complete `JSDoc` support, including typedefs.
-* Strong support for HTML and Markdown output
-* Documentation coverage, statistics, and validation
+-   Robust and complete `JSDoc` support, including typedefs.
+-   Strong support for HTML and Markdown output
+-   Documentation coverage, statistics, and validation
 
 documentation is an OPEN Open Source Project. This means that:
 

bin/documentation.js

@@ -24,28 +24,29 @@ var argv = yargs
   .version(function () {
     return require('../package').version;
   })
-  .usage('Usage:\n\n' +
-    '# generate markdown docs for index.js and files it references\n' +
-    '$0 build index.js -f md\n\n' +
+  .usage(`Usage:
 
-    '# generate html docs for all files in src\n' +
-    '$0 build src/** -f html -o docs\n\n' +
+  # generate markdown docs for index.js and files it references 
+  $0 build index.js -f md 
 
-    '# document index.js, ignoring any files it requires or imports\n' +
-    '$0 build index.js -f md --shallow\n\n' +
+  # generate html docs for all files in src 
+  $0 build src/** -f html -o docs 
 
-    '# build, serve, and live-update html docs for app.js\n' +
-    '$0 serve app.js\n\n' +
+  # document index.js, ignoring any files it requires or imports 
+  $0 build index.js -f md --shallow 
 
-    '# validate JSDoc syntax in util.js\n' +
-    '$0 lint util.js\n\n' +
+  # build, serve, and live-update html docs for app.js 
+  $0 serve app.js 
 
-    '# update the API section of README.md with docs from index.js\n' +
-    '$0 readme index.js --section=API\n\n' +
+  # validate JSDoc syntax in util.js 
+  $0 lint util.js 
 
-    '# build docs for all values exported by index.js\n' +
-    '$0 build --document-exported index.js'
-  )
+  # update the API section of README.md with docs from index.js 
+  $0 readme index.js --section=API 
+
+  # build docs for all values exported by index.js 
+  $0 build --document-exported index.js
+`)
   .recommendCommands()
   .help()
   .argv;

declarations/comment.js

@@ -0,0 +1,131 @@
+declare type DocumentationConfig = {
+  polyglot?: boolean,
+  inferPrivate?: boolean,
+  noPackage?: boolean,
+  toc?: Array<Object>,
+  paths?: { [key: string]: number },
+  defaultGlobals?: boolean,
+  defaultGlobalsEnvs?: Array<string>,
+  external?: Array<string>,
+  theme: string,
+  requireExtension?: Array<string>,
+  parseExtension: Array<string>
+};
+
+declare type InputsConfig = {
+  inputs: Array<SourceFile>,
+  config: DocumentationConfig
+};
+
+declare type CommentError = {
+  message: string,
+  commentLineNumber?: number
+};
+
+declare type DoctrineType = {
+  elements?: Array<DoctrineType>,
+  expression?: DoctrineType,
+  applications?: Array<DoctrineType>,
+  type: string,
+  name?: string
+};
+
+declare type CommentLoc = {
+  start: {
+    line: number
+  },
+  end: {
+    line: number
+  }
+};
+
+declare type SourceFile = {
+  source?: string,
+  file: string
+};
+
+declare type CommentContext = {
+  sortKey: string,
+  file: string,
+  ast: Object,
+  loc: CommentLoc,
+  code: string,
+  github?: CommentContextGitHub
+};
+
+declare type CommentContextGitHub = {
+  path: string,
+  url: string
+};
+
+declare type CommentTag = {
+  name?: string,
+  title: string,
+  description?: Object,
+  default?: any,
+  lineNumber?: number,
+  type?: DoctrineType,
+  properties?: Array<CommentTag>
+};
+
+declare type CommentMembers = {
+  static: Array<Comment>,
+  instance: Array<Comment>,
+  events: Array<Comment>
+};
+
+declare type CommentExample = {
+  caption?: string,
+  description?: Object
+};
+
+declare type Remark = {
+  type: string,
+  children: Array<Object>
+};
+
+declare type Comment = {
+  errors: Array<CommentError>,
+  tags: Array<CommentTag>,
+
+  augments: Array<CommentTag>,
+  errors: Array<CommentExample>,
+  examples: Array<CommentExample>,
+  params: Array<CommentTag>,
+  properties: Array<CommentTag>,
+  returns: Array<CommentTag>,
+  sees: Array<CommentTag>,
+  throws: Array<CommentTag>,
+  todos: Array<CommentTag>,
+
+  description?: Remark,
+  summary?: Remark,
+  deprecated?: Remark,
+  classdesc?: Remark,
+
+  members: CommentMembers,
+
+  name?: string,
+  kind?: string,
+  memberof?: string,
+  scope?: string,
+  access?: string,
+  alias?: string,
+
+  copyright?: string,
+  author?: string,
+  license?: string,
+  version?: string,
+  since?: string,
+  lends?: string,
+  override?: boolean,
+
+  type?: DoctrineType,
+
+  context: CommentContext,
+
+  path?: Array<{
+    name: string,
+    scope: string
+  }>
+};

default_theme/index._

@@ -2,7 +2,7 @@
 <html>
 <head>
   <meta charset='utf-8' />
-  <title><%- options.name %> <%- options.version %> | Documentation</title>
+  <title><%- config['project-name'] %> <%- config['project-version'] %> | Documentation</title>
   <meta name='viewport' content='width=device-width,initial-scale=1'>
   <link href='assets/bass.css' type='text/css' rel='stylesheet' />
   <link href='assets/style.css' type='text/css' rel='stylesheet' />
@@ -13,8 +13,8 @@
     <div class='clearfix md-mxn2'>
       <div class='fixed xs-hide fix-3 overflow-auto max-height-100'>
         <div class='py1 px2'>
-          <h3 class='mb0 no-anchor'><%- options.name %></h3>
-          <div class='mb1'><code><%- options.version %></code></div>
+          <h3 class='mb0 no-anchor'><%- config['project-name'] %></h3>
+          <div class='mb1'><code><%- config['project-version'] %></code></div>
           <input
             placeholder='Filter'
             id='filter-input'

default_theme/index.js

@@ -8,28 +8,28 @@ var fs = require('fs'),
   concat = require('concat-stream'),
   GithubSlugger = require('github-slugger'),
   createFormatters = require('../').util.createFormatters,
-  createLinkerStack = require('../').util.createLinkerStack,
+  LinkerStack = require('../').util.LinkerStack,
   hljs = require('highlight.js');
 
-module.exports = function (comments, options, callback) {
+module.exports = function (comments/*: Array<Comment> */, config/*: DocumentationConfig */) {
 
-  var linkerStack = createLinkerStack(options)
+  var linkerStack = new LinkerStack(config)
     .namespaceResolver(comments, function (namespace) {
       var slugger = new GithubSlugger();
       return '#' + slugger.slug(namespace);
     });
 
   var formatters = createFormatters(linkerStack.link);
 
-  hljs.configure(options.hljs || {});
+  hljs.configure(config.hljs || {});
 
   var sharedImports = {
     imports: {
-      slug: function (str) {
+      slug(str) {
         var slugger = new GithubSlugger();
         return slugger.slug(str);
       },
-      shortSignature: function (section) {
+      shortSignature(section) {
         var prefix = '';
         if (section.kind === 'class') {
           prefix = 'new ';
@@ -38,21 +38,21 @@ module.exports = function (comments, options, callback) {
         }
         return prefix + section.name + formatters.parameters(section, true);
       },
-      signature: function (section) {
+      signature(section) {
         var returns = '';
         var prefix = '';
         if (section.kind === 'class') {
           prefix = 'new ';
         } else if (section.kind !== 'function') {
           return section.name;
         }
-        if (section.returns) {
+        if (section.returns.length) {
           returns = ': ' +
             formatters.type(section.returns[0].type);
         }
         return prefix + section.name + formatters.parameters(section) + returns;
       },
-      md: function (ast, inline) {
+      md(ast, inline) {
         if (inline && ast && ast.children.length && ast.children[0].type === 'paragraph') {
           ast = {
             type: 'root',
@@ -63,8 +63,8 @@ module.exports = function (comments, options, callback) {
       },
       formatType: formatters.type,
       autolink: formatters.autolink,
-      highlight: function (example) {
-        if (options.hljs && options.hljs.highlightAuto) {
+      highlight(example) {
+        if (config.hljs && config.hljs.highlightAuto) {
           return hljs.highlightAuto(example).value;
         }
         return hljs.highlight('js', example).value;
@@ -79,14 +79,16 @@ module.exports = function (comments, options, callback) {
   var pageTemplate = _.template(fs.readFileSync(path.join(__dirname, 'index._'), 'utf8'),  sharedImports);
 
   // push assets into the pipeline as well.
-  vfs.src([__dirname + '/assets/**'], { base: __dirname })
-    .pipe(concat(function (files) {
-      callback(null, files.concat(new File({
-        path: 'index.html',
-        contents: new Buffer(pageTemplate({
-          docs: comments,
-          options: options
-        }), 'utf8')
-      })));
-    }));
+  return new Promise(resolve => {
+    vfs.src([__dirname + '/assets/**'], { base: __dirname })
+      .pipe(concat(function (files) {
+        resolve(files.concat(new File({
+          path: 'index.html',
+          contents: new Buffer(pageTemplate({
+            docs: comments,
+            config: config
+          }), 'utf8')
+        })));
+      }));
+  });
 };