Skip to content

Commit

Permalink
feat(core): Switch to Promises everywhere. Adopt Node v4 ES6 (#648)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
tmcw committed Jan 27, 2017
1 parent 898faa0 commit 631c692
Show file tree
Hide file tree
Showing 225 changed files with 4,506 additions and 13,383 deletions.
18 changes: 13 additions & 5 deletions .eslintrc
Original file line number Diff line number Diff line change
@@ -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,
Expand All @@ -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,
Expand All @@ -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
}
}
12 changes: 12 additions & 0 deletions .flowconfig
Original file line number Diff line number Diff line change
@@ -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
30 changes: 15 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down
33 changes: 17 additions & 16 deletions bin/documentation.js
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
131 changes: 131 additions & 0 deletions declarations/comment.js
Original file line number Diff line number Diff line change
@@ -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
}>
};
6 changes: 3 additions & 3 deletions default_theme/index._
Original file line number Diff line number Diff line change
Expand Up @@ -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' />
Expand All @@ -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'
Expand Down
44 changes: 23 additions & 21 deletions default_theme/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 ';
Expand All @@ -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',
Expand All @@ -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;
Expand All @@ -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')
})));
}));
});
};
Loading

0 comments on commit 631c692

Please sign in to comment.