Skip to content

Commit 631c692

Browse files
tmcwtmcw
authored
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
1 parent 898faa0 commit 631c692

File tree

225 files changed

+4506
-13383
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

225 files changed

+4506
-13383
lines changed

‎.eslintrc

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
{
22
"root": true,
3-
"parser": "espree",
3+
"parser": "babel-eslint",
4+
"parserOptions": {
5+
"sourceType": "script"
6+
},
7+
"plugins": [
8+
"flowtype"
9+
],
410
"rules": {
511
"space-in-parens": 2,
612
"space-before-blocks": 2,
@@ -21,8 +27,8 @@
2127
"no-new": 2,
2228
"key-spacing": 2,
2329
"no-multi-spaces": 2,
24-
"valid-jsdoc": 2,
2530
"brace-style": 2,
31+
"object-shorthand": ["error", "always", { "avoidQuotes": true }],
2632
"no-throw-literal": 2,
2733
"no-self-compare": 2,
2834
"no-void": 2,
@@ -32,13 +38,15 @@
3238
"quotes": [2, "single"],
3339
"indent": [2, 2],
3440
"curly": 2,
41+
"strict": [2, "global"],
3542
"no-shadow": 0,
36-
"no-undef": 2
43+
"no-undef": 2,
44+
"flowtype/define-flow-type": 1,
45+
"flowtype/use-flow-type": 1
3746
},
3847
"extends": "eslint:recommended",
3948
"env": {
4049
"node": true,
41-
"es6": true,
42-
"browser": true
50+
"es6": true
4351
}
4452
}

‎.flowconfig

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[ignore]
2+
.*node_modules/.cache/.*
3+
.*node_modules/conventional-changelog-core/test/fixtures/.*
4+
.*/test/fixture/.*
5+
6+
[include]
7+
8+
[libs]
9+
declarations/
10+
11+
[options]
12+
module.ignore_non_literal_requires=true

‎README.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -46,21 +46,21 @@ lets you run `documentation` as a [Gulp](http://gulpjs.com/) build task.
4646

4747
## Examples
4848

49-
* [HTML output with default template](http://documentation.js.org/html-example/)
50-
* [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
51-
* [JSON](http://documentation.js.org/html-example/index.json)
49+
- [HTML output with default template](http://documentation.js.org/html-example/)
50+
- [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
51+
- [JSON](http://documentation.js.org/html-example/index.json)
5252

5353
## Documentation
5454

55-
* [Getting Started](docs/GETTING_STARTED.md): start here
56-
* [Usage](docs/USAGE.md): how to use documentation.js
57-
* [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
58-
* [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
59-
* [Configuring documentation.js](docs/CONFIG.md)
60-
* [FAQ](docs/FAQ.md)
61-
* [Troubleshooting](docs/TROUBLESHOOTING.md)
62-
* [Theming](docs/THEMING.md): tips for theming documentation output in HTML
63-
* [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
55+
- [Getting Started](docs/GETTING_STARTED.md): start here
56+
- [Usage](docs/USAGE.md): how to use documentation.js
57+
- [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
58+
- [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
59+
- [Configuring documentation.js](docs/CONFIG.md)
60+
- [FAQ](docs/FAQ.md)
61+
- [Troubleshooting](docs/TROUBLESHOOTING.md)
62+
- [Theming](docs/THEMING.md): tips for theming documentation output in HTML
63+
- [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
6464

6565
## User Guide
6666

@@ -116,9 +116,9 @@ _We have plenty of
116116
[issues](https://github.com/documentationjs/documentation/issues) that we'd
117117
love help with._
118118

119-
* Robust and complete `JSDoc` support, including typedefs.
120-
* Strong support for HTML and Markdown output
121-
* Documentation coverage, statistics, and validation
119+
- Robust and complete `JSDoc` support, including typedefs.
120+
- Strong support for HTML and Markdown output
121+
- Documentation coverage, statistics, and validation
122122

123123
documentation is an OPEN Open Source Project. This means that:
124124

‎bin/documentation.js

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,28 +24,29 @@ var argv = yargs
2424
.version(function () {
2525
return require('../package').version;
2626
})
27-
.usage('Usage:\n\n' +
28-
'# generate markdown docs for index.js and files it references\n' +
29-
'$0 build index.js -f md\n\n' +
27+
.usage(`Usage:
3028
31-
'# generate html docs for all files in src\n' +
32-
'$0 build src/** -f html -o docs\n\n' +
29+
# generate markdown docs for index.js and files it references
30+
$0 build index.js -f md
3331
34-
'# document index.js, ignoring any files it requires or imports\n' +
35-
'$0 build index.js -f md --shallow\n\n' +
32+
# generate html docs for all files in src
33+
$0 build src/** -f html -o docs
3634
37-
'# build, serve, and live-update html docs for app.js\n' +
38-
'$0 serve app.js\n\n' +
35+
# document index.js, ignoring any files it requires or imports
36+
$0 build index.js -f md --shallow
3937
40-
'# validate JSDoc syntax in util.js\n' +
41-
'$0 lint util.js\n\n' +
38+
# build, serve, and live-update html docs for app.js
39+
$0 serve app.js
4240
43-
'# update the API section of README.md with docs from index.js\n' +
44-
'$0 readme index.js --section=API\n\n' +
41+
# validate JSDoc syntax in util.js
42+
$0 lint util.js
4543
46-
'# build docs for all values exported by index.js\n' +
47-
'$0 build --document-exported index.js'
48-
)
44+
# update the API section of README.md with docs from index.js
45+
$0 readme index.js --section=API
46+
47+
# build docs for all values exported by index.js
48+
$0 build --document-exported index.js
49+
`)
4950
.recommendCommands()
5051
.help()
5152
.argv;

‎declarations/comment.js

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
declare type DocumentationConfig = {
2+
polyglot?: boolean,
3+
inferPrivate?: boolean,
4+
noPackage?: boolean,
5+
toc?: Array<Object>,
6+
paths?: { [key: string]: number },
7+
defaultGlobals?: boolean,
8+
defaultGlobalsEnvs?: Array<string>,
9+
external?: Array<string>,
10+
theme: string,
11+
requireExtension?: Array<string>,
12+
parseExtension: Array<string>
13+
};
14+
15+
declare type InputsConfig = {
16+
inputs: Array<SourceFile>,
17+
config: DocumentationConfig
18+
};
19+
20+
declare type CommentError = {
21+
message: string,
22+
commentLineNumber?: number
23+
};
24+
25+
declare type DoctrineType = {
26+
elements?: Array<DoctrineType>,
27+
expression?: DoctrineType,
28+
applications?: Array<DoctrineType>,
29+
type: string,
30+
name?: string
31+
};
32+
33+
declare type CommentLoc = {
34+
start: {
35+
line: number
36+
},
37+
end: {
38+
line: number
39+
}
40+
};
41+
42+
declare type SourceFile = {
43+
source?: string,
44+
file: string
45+
};
46+
47+
declare type CommentContext = {
48+
sortKey: string,
49+
file: string,
50+
ast: Object,
51+
loc: CommentLoc,
52+
code: string,
53+
github?: CommentContextGitHub
54+
};
55+
56+
declare type CommentContextGitHub = {
57+
path: string,
58+
url: string
59+
};
60+
61+
declare type CommentTag = {
62+
name?: string,
63+
title: string,
64+
description?: Object,
65+
default?: any,
66+
lineNumber?: number,
67+
type?: DoctrineType,
68+
properties?: Array<CommentTag>
69+
};
70+
71+
declare type CommentMembers = {
72+
static: Array<Comment>,
73+
instance: Array<Comment>,
74+
events: Array<Comment>
75+
};
76+
77+
declare type CommentExample = {
78+
caption?: string,
79+
description?: Object
80+
};
81+
82+
declare type Remark = {
83+
type: string,
84+
children: Array<Object>
85+
};
86+
87+
declare type Comment = {
88+
errors: Array<CommentError>,
89+
tags: Array<CommentTag>,
90+
91+
augments: Array<CommentTag>,
92+
errors: Array<CommentExample>,
93+
examples: Array<CommentExample>,
94+
params: Array<CommentTag>,
95+
properties: Array<CommentTag>,
96+
returns: Array<CommentTag>,
97+
sees: Array<CommentTag>,
98+
throws: Array<CommentTag>,
99+
todos: Array<CommentTag>,
100+
101+
description?: Remark,
102+
summary?: Remark,
103+
deprecated?: Remark,
104+
classdesc?: Remark,
105+
106+
members: CommentMembers,
107+
108+
name?: string,
109+
kind?: string,
110+
memberof?: string,
111+
scope?: string,
112+
access?: string,
113+
alias?: string,
114+
115+
copyright?: string,
116+
author?: string,
117+
license?: string,
118+
version?: string,
119+
since?: string,
120+
lends?: string,
121+
override?: boolean,
122+
123+
type?: DoctrineType,
124+
125+
context: CommentContext,
126+
127+
path?: Array<{
128+
name: string,
129+
scope: string
130+
}>
131+
};

‎default_theme/index._

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<html>
33
<head>
44
<meta charset='utf-8' />
5-
<title><%- options.name %> <%- options.version %> | Documentation</title>
5+
<title><%- config['project-name'] %> <%- config['project-version'] %> | Documentation</title>
66
<meta name='viewport' content='width=device-width,initial-scale=1'>
77
<link href='assets/bass.css' type='text/css' rel='stylesheet' />
88
<link href='assets/style.css' type='text/css' rel='stylesheet' />
@@ -13,8 +13,8 @@
1313
<div class='clearfix md-mxn2'>
1414
<div class='fixed xs-hide fix-3 overflow-auto max-height-100'>
1515
<div class='py1 px2'>
16-
<h3 class='mb0 no-anchor'><%- options.name %></h3>
17-
<div class='mb1'><code><%- options.version %></code></div>
16+
<h3 class='mb0 no-anchor'><%- config['project-name'] %></h3>
17+
<div class='mb1'><code><%- config['project-version'] %></code></div>
1818
<input
1919
placeholder='Filter'
2020
id='filter-input'

‎default_theme/index.js

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,28 +8,28 @@ var fs = require('fs'),
88
concat = require('concat-stream'),
99
GithubSlugger = require('github-slugger'),
1010
createFormatters = require('../').util.createFormatters,
11-
createLinkerStack = require('../').util.createLinkerStack,
11+
LinkerStack = require('../').util.LinkerStack,
1212
hljs = require('highlight.js');
1313

14-
module.exports = function (comments, options, callback) {
14+
module.exports = function (comments/*: Array<Comment> */, config/*: DocumentationConfig */) {
1515

16-
var linkerStack = createLinkerStack(options)
16+
var linkerStack = new LinkerStack(config)
1717
.namespaceResolver(comments, function (namespace) {
1818
var slugger = new GithubSlugger();
1919
return '#' + slugger.slug(namespace);
2020
});
2121

2222
var formatters = createFormatters(linkerStack.link);
2323

24-
hljs.configure(options.hljs || {});
24+
hljs.configure(config.hljs || {});
2525

2626
var sharedImports = {
2727
imports: {
28-
slug: function (str) {
28+
slug(str) {
2929
var slugger = new GithubSlugger();
3030
return slugger.slug(str);
3131
},
32-
shortSignature: function (section) {
32+
shortSignature(section) {
3333
var prefix = '';
3434
if (section.kind === 'class') {
3535
prefix = 'new ';
@@ -38,21 +38,21 @@ module.exports = function (comments, options, callback) {
3838
}
3939
return prefix + section.name + formatters.parameters(section, true);
4040
},
41-
signature: function (section) {
41+
signature(section) {
4242
var returns = '';
4343
var prefix = '';
4444
if (section.kind === 'class') {
4545
prefix = 'new ';
4646
} else if (section.kind !== 'function') {
4747
return section.name;
4848
}
49-
if (section.returns) {
49+
if (section.returns.length) {
5050
returns = ': ' +
5151
formatters.type(section.returns[0].type);
5252
}
5353
return prefix + section.name + formatters.parameters(section) + returns;
5454
},
55-
md: function (ast, inline) {
55+
md(ast, inline) {
5656
if (inline && ast && ast.children.length && ast.children[0].type === 'paragraph') {
5757
ast = {
5858
type: 'root',
@@ -63,8 +63,8 @@ module.exports = function (comments, options, callback) {
6363
},
6464
formatType: formatters.type,
6565
autolink: formatters.autolink,
66-
highlight: function (example) {
67-
if (options.hljs && options.hljs.highlightAuto) {
66+
highlight(example) {
67+
if (config.hljs && config.hljs.highlightAuto) {
6868
return hljs.highlightAuto(example).value;
6969
}
7070
return hljs.highlight('js', example).value;
@@ -79,14 +79,16 @@ module.exports = function (comments, options, callback) {
7979
var pageTemplate = _.template(fs.readFileSync(path.join(__dirname, 'index._'), 'utf8'), sharedImports);
8080

8181
// push assets into the pipeline as well.
82-
vfs.src([__dirname + '/assets/**'], { base: __dirname })
83-
.pipe(concat(function (files) {
84-
callback(null, files.concat(new File({
85-
path: 'index.html',
86-
contents: new Buffer(pageTemplate({
87-
docs: comments,
88-
options: options
89-
}), 'utf8')
90-
})));
91-
}));
82+
return new Promise(resolve => {
83+
vfs.src([__dirname + '/assets/**'], { base: __dirname })
84+
.pipe(concat(function (files) {
85+
resolve(files.concat(new File({
86+
path: 'index.html',
87+
contents: new Buffer(pageTemplate({
88+
docs: comments,
89+
config: config
90+
}), 'utf8')
91+
})));
92+
}));
93+
});
9294
};

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy