Skip to content

Commit 7777d47

Browse files
developitdevelopit
committed
Merge pull request #1 from documentationjs/master
merge upstream
2 parents cabef43 + 63c0ca6 commit 7777d47

Some content is hidden

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

49 files changed

+2727
-100
lines changed

‎CHANGELOG.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,13 @@ about escaping and properly formatting certain elements.
7575
documentation.js returns to 100% test coverage, so every single line
7676
of code is covered by our large library of text fixtures and specific tests.
7777

78+
**--lint mode**
79+
80+
Specifying the `--lint` flag makes documentation.js check for non-standard
81+
types, like `String`, or missing namespaces. If the encountered files have
82+
any problems, it pretty-prints helpful debug messages and exits with status 1,
83+
and otherwise exits with no output and status 0.
84+
7885
## 2.0.1
7986

8087
* Fixes `@param` tags that refer to properties of unmentioned objects: these

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
[![Build Status](https://circleci.com/gh/documentationjs/documentation.svg?style=svg)](https://circleci.com/gh/documentationjs/documentation) [![Coverage Status](https://coveralls.io/repos/documentationjs/documentation/badge.svg?branch=master)](https://coveralls.io/r/documentationjs/documentation?branch=master)
44
[![npm version](https://badge.fury.io/js/documentation.svg)](http://badge.fury.io/js/documentation)
5+
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/documentationjs/documentation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
56

67
A **documentation generation system** that's
78
_beautiful_ by default, _flexible_ across formats and styles, and

‎bin/documentation.js

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ var documentation = require('../'),
88
streamArray = require('stream-array'),
99
fs = require('fs'),
1010
vfs = require('vinyl-fs'),
11-
walk = require('../lib/walk'),
12-
formatError = require('../lib/format_error'),
11+
lint = require('../lib/lint'),
1312
args = require('../lib/args.js');
1413

1514
var parsedArgs = args(process.argv.slice(2)),
@@ -22,11 +21,15 @@ documentation(parsedArgs.inputs, parsedArgs.options, function (err, comments) {
2221
throw err;
2322
}
2423

25-
walk(comments, function (comment) {
26-
comment.errors.forEach(function (error) {
27-
console.error(formatError(comment, error));
28-
});
29-
});
24+
if (parsedArgs.options.lint) {
25+
var lintOutput = lint.format(comments);
26+
if (lintOutput) {
27+
console.log(lintOutput);
28+
process.exit(1);
29+
} else {
30+
process.exit(0);
31+
}
32+
}
3033

3134
formatter(comments, formatterOptions, function (err, output) {
3235
if (outputLocation !== 'stdout') {

‎index.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ module.exports = function (indexes, options, callback) {
9292
return memo.concat(parseFn(file));
9393
}, [])
9494
.map(pipeline(
95-
lint,
95+
lint.lint,
9696
inferName(),
9797
inferKind(),
9898
inferParams(),

‎lib/args.js

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ function parse(args) {
1515
choices: ['json', 'md', 'html']
1616
})
1717

18-
.describe('lint', 'check output for common style and uniformity mistakes')
18+
.option('lint', {
19+
describe: 'check output for common style and uniformity mistakes',
20+
type: 'boolean'
21+
})
1922

2023
.describe('t', 'specify a theme: this must be a valid theme module')
2124
.alias('t', 'theme')
@@ -112,6 +115,7 @@ module.exports = function (args) {
112115
options: {
113116
private: argv.private,
114117
transform: transform,
118+
lint: argv.lint,
115119
github: argv.github,
116120
polyglot: argv.polyglot,
117121
order: config.order || [],

‎lib/format_error.js

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎lib/hierarchy.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ module.exports = function (comments) {
4444
scope = segment[0],
4545
name = segment[1];
4646

47-
if (!node.members[scope][name]) {
47+
if (!node.members[scope].hasOwnProperty(name)) {
4848
node.members[scope][name] = {
4949
comments: [],
5050
members: {

‎lib/infer/kind.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@ module.exports = function () {
2828
}
2929

3030
types.visit(comment.context.ast, {
31+
visitClassDeclaration: function () {
32+
comment.kind = 'class';
33+
this.abort();
34+
},
3135
visitFunction: function (path) {
3236
if (path.value && path.value.id && path.value.id.name && !!/^[A-Z]/.exec(path.value.id.name)) {
3337
comment.kind = 'class';

‎lib/infer/membership.js

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,10 +99,12 @@ module.exports = function () {
9999
*
100100
* @param {Object} comment comment for which to infer memberships
101101
* @param {Array<string>} identifiers array of identifier names
102+
* @param {string} explicitScope if derived from an es6 class, whether or
103+
* not this method had the static keyword
102104
* @returns {undefined} mutates `comment`
103105
* @private
104106
*/
105-
function inferMembershipFromIdentifiers(comment, identifiers) {
107+
function inferMembershipFromIdentifiers(comment, identifiers, explicitScope) {
106108
if (identifiers.length === 1 && identifiers[0] === 'module' && comment.name === 'exports') {
107109
comment.name = inferModuleName(currentModule || comment);
108110
return;
@@ -123,7 +125,11 @@ module.exports = function () {
123125
comment.scope = 'instance';
124126
} else {
125127
comment.memberof = identifiers.join('.');
126-
comment.scope = 'static';
128+
if (explicitScope !== undefined) {
129+
comment.scope = explicitScope;
130+
} else {
131+
comment.scope = 'static';
132+
}
127133
}
128134
}
129135

@@ -206,6 +212,18 @@ module.exports = function () {
206212
inferMembershipFromIdentifiers(comment, identifiers);
207213
}
208214

215+
// class Foo { bar() { } }
216+
if (n.MethodDefinition.check(path.node) &&
217+
n.ClassBody.check(path.parent.node) &&
218+
n.ClassDeclaration.check(path.parent.parent.node)) {
219+
identifiers = [path.parent.parent.node.id.name];
220+
var scope = 'instance';
221+
if (path.node.static == true) {
222+
scope = 'static';
223+
}
224+
inferMembershipFromIdentifiers(comment, identifiers, scope);
225+
}
226+
209227
return comment;
210228
};
211229
}

‎lib/infer/params.js

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
'use strict';
22

33
var types = require('ast-types'),
4+
extend = require('extend'),
45
flowDoctrine = require('../flow_doctrine');
56

67

@@ -13,6 +14,17 @@ var types = require('ast-types'),
1314
*/
1415
module.exports = function () {
1516
return function inferParams(comment) {
17+
18+
/**
19+
* Given a parameter like
20+
*
21+
* function a(b = 1)
22+
*
23+
* Format it as an optional parameter in JSDoc land
24+
*
25+
* @param {Object} param ESTree node
26+
* @returns {Object} JSDoc param
27+
*/
1628
function paramWithDefaultToDoc(param) {
1729
var newParam = paramToDoc(param.left);
1830
var optionalParam = {
@@ -32,12 +44,30 @@ module.exports = function () {
3244
return optionalParam;
3345
}
3446

35-
function paramToDoc(param) {
47+
function destructuringPropertyToDoc(i, property) {
48+
return paramToDoc(extend({}, property, {
49+
name: '$' + i + '.' + property.key.name
50+
}));
51+
}
52+
53+
function destructuringParamToDoc(param, i) {
54+
return [{
55+
title: 'param',
56+
name: '$' + i,
57+
type: flowDoctrine(param)
58+
}].concat(param.properties.map(destructuringPropertyToDoc.bind(null, i)));
59+
}
60+
61+
function paramToDoc(param, i) {
3662
// ES6 default
3763
if (param.type === 'AssignmentPattern') {
3864
return paramWithDefaultToDoc(param);
3965
}
4066

67+
if (param.type === 'ObjectPattern') {
68+
return destructuringParamToDoc(param, i);
69+
}
70+
4171
var newParam = {
4272
title: 'param',
4373
name: param.name,
@@ -52,7 +82,12 @@ module.exports = function () {
5282
return newParam;
5383
}
5484

85+
function abort() {
86+
return false
87+
}
88+
5589
types.visit(comment.context.ast, {
90+
visitCallExpression: abort,
5691
visitFunction: function (path) {
5792

5893
// Ensure that explicitly specified parameters are not overridden
@@ -65,13 +100,13 @@ module.exports = function () {
65100
var paramOrder = {};
66101
var i = 0;
67102

68-
path.value.params.forEach(function (param) {
103+
path.value.params.forEach(function (param, j) {
69104
if (existingParams[param.name] === undefined) {
70105
if (!comment.params) {
71106
comment.params = [];
72107
}
73108

74-
comment.params.push(paramToDoc(param));
109+
comment.params = comment.params.concat(paramToDoc(param, j));
75110
}
76111
paramOrder[param.name] = i++;
77112
});

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