diff --git a/__tests__/__snapshots__/bin.js.snap b/__tests__/__snapshots__/bin.js.snap index 1d55f33d1..9c7329263 100644 --- a/__tests__/__snapshots__/bin.js.snap +++ b/__tests__/__snapshots__/bin.js.snap @@ -896,7 +896,7 @@ k.isArrayOfBuffers();

a typedef with nested properties

-
CustomError(other: any, also: any)
+
CustomError
@@ -908,27 +908,6 @@ k.isArrayOfBuffers(); -
Parameters
-
- -
-
- other (any) - -
- -
- -
-
- also (any) - -
- -
- -
-
Properties
diff --git a/__tests__/__snapshots__/test.js.snap b/__tests__/__snapshots__/test.js.snap index 57a8751a4..1a0c11e9e 100644 --- a/__tests__/__snapshots__/test.js.snap +++ b/__tests__/__snapshots__/test.js.snap @@ -1601,7 +1601,7 @@ k.isArrayOfBuffers();

a typedef with nested properties

-
CustomError(other: any, also: any)
+
CustomError
@@ -1613,27 +1613,6 @@ k.isArrayOfBuffers(); -
Parameters
-
- -
-
- other (any) - -
- -
- -
-
- also (any) - -
- -
- -
-
Properties
diff --git a/__tests__/bin.js b/__tests__/bin.js index 084cfe4d7..b5b8ae5d2 100644 --- a/__tests__/bin.js +++ b/__tests__/bin.js @@ -163,10 +163,6 @@ test('--config', async function() { var dst = path.join(os.tmpdir(), (Date.now() + Math.random()).toString()); fs.mkdirSync(dst); var outputIndex = path.join(dst, 'index.html'); - var expectedOutputPath = path.join( - __dirname, - 'fixture/html/nested.config-output.html' - ); const data = await documentation( [ 'build -c fixture/html/documentation.yml -f html fixture/html/nested.input.js -o ' + diff --git a/__tests__/fixture/html/nested.config-output.html b/__tests__/fixture/html/nested.config-output.html deleted file mode 100644 index e08471d15..000000000 --- a/__tests__/fixture/html/nested.config-output.html +++ /dev/null @@ -1,1359 +0,0 @@ - - - - - documentation 4.0.0-rc.0 | Documentation - - - - - - -
-
-
-
-

documentation

-
4.0.0-rc.0
- -
- -
-
- Need help reading this? -
-
-
-
- - -
- -

- Highlighted section -

- - -

The public key is a base64 encoded string of a protobuf containing an RSA DER -buffer. This uses a node buffer to pass the base64 encoded public key protobuf -to the multihash for ID generation.

-
var PeerId = require('peer-id')
-
-PeerId.create({ bits: 1024 }, (err, id) => {
-  console.log(JSON.stringify(id.toJSON(), null, 2)
-})
-
{
-  "id": "Qma9T5YraSnpRDZqRR4krcSJabThc8nwZuJV3LercPHufi",
-  "privKey": "CAAS4AQwggJcAgEAAoGBAMBgbIqyOL26oV3nGPBYrdpbv..",
-  "pubKey": "CAASogEwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMBgbIqyOL26oV3nGPBYrdpbvzCY..."
-}
-
- - -
-
- - - -
- - -
- -

- Klass -

- - -
- - -

Creates a new Klass

- - -
new Klass(foo: any)
- - -

- Extends - - Stream.Writable - -

- - - - - - - - - - -
Parameters
-
- -
-
- foo (any) - -
- -
- -
- - - - - - - - - - - -
Static Members
-
- -
-
-
- ▸ - isClass(other, also) -
-
- -
- -
-
-
- ▸ - isWeird(other) -
-
- -
- -
-
-
- ▸ - isBuffer(buf, size) -
-
- -
- -
-
-
- ▸ - isArrayOfBuffers(buffers) -
-
- -
- -
-
-
- ▸ - MAGIC_NUMBER -
-
- -
- -
- - - - -
Instance Members
-
- -
-
-
- ▸ - getFoo() -
-
- -
- -
-
-
- ▸ - withOptions(options, otherOptions) -
-
- -
- -
- - - - -
Events
-
- -
-
-
- ▸ - event -
-
- -
- -
- - -
- - - - -
- - -
- -

- CustomError -

- - -
- - -

a typedef with nested properties

- - -
CustomError(other: any, also: any)
- - - - - - - - - - - -
Parameters
-
- -
-
- other (any) - -
- -
- -
-
- also (any) - -
- -
- -
- - - -
Properties
-
- -
- error (object) - : An error - - -
    - -
  • error.code string - -

    The error's code

    -
    • - -
  • error.description string - -

    The error's description

    -
    • - -
- -
- -
- - - - - - - - - - - - - -
- - - - -
- - -
- -

- bar -

- - -
- - -

Get an instance of Klass. Will make -a klass instance multiword, -like a klass

- - -
bar(): Klass
- - - - - - - - - - - - - - - - -
Returns
- Klass: - that class - - - - - - - - - - - - - - -
- - - - -
- - -
- -

- bar -

- - -
- - -

Rest property function

- - -
bar(toys: ...Number): undefined
- - - - - - - - - - - -
Parameters
-
- -
-
- toys (...Number) - -
- -
- -
- - - - - - -
Returns
- undefined: - nothing - - - - - - - - - - - - - - -
- - - - -
- - -
- -

- bar -

- - -
- - -

Get an instance of Klass. Will make -a klass instance multiword, -like a klass. This needs a number input.

- - -
bar(): undefined
- - - - - - - - - - - - - - - - -
Returns
- undefined: - nothing - - - - - - - - - - - - - - -
- - - - -
- - -
- -

- Foo -

- - -
- - -

This is Foo

- - -
new Foo()
- - - - - - - - - - - - - - - - - - - - - - - -
Instance Members
-
- -
-
-
- ▸ - bar -
-
- -
- -
- - - - -
- - - - -
- - -
- -

- customStreams -

- - -
- - -

I am the container of stream types

- - -
customStreams
- - - - - - - - - - - - - - - - - - - - - -
Static Members
-
- -
-
-
- ▸ - new passthrough() -
-
- -
- -
- - - - - - -
- - - -
-
-
- - - - diff --git a/__tests__/lib/parse.js b/__tests__/lib/parse.js index 2349ec8ff..794f98a48 100644 --- a/__tests__/lib/parse.js +++ b/__tests__/lib/parse.js @@ -434,6 +434,22 @@ test('parse - @function', function() { kind: 'function', name: 'name' }); + + // When @function takes a name, it is acting as a shorthand for @name and + // should detach from code the same way @name does. + expect( + evaluate(function() { + /** @function */ + function foo() {} + })[0].context.ast + ).toBeDefined(); + + expect( + evaluate(function() { + /** @function name */ + function foo() {} + })[0].context.ast + ).toBeUndefined(); }); test('parse - @global', function() { @@ -640,6 +656,13 @@ test('parse - @name', function() { /** @name test */ })[0].name ).toBe('test'); + + expect( + evaluate(function() { + /** @name foo */ + const bar = 0; + })[0].context.ast + ).toBeUndefined(); }); test('parse - @namespace', function() { diff --git a/declarations/comment.js b/declarations/comment.js index 17d2c3e63..9d0cc71b5 100644 --- a/declarations/comment.js +++ b/declarations/comment.js @@ -44,7 +44,7 @@ type SourceFile = { type CommentContext = { sortKey: string, file: string, - ast: Object, + ast?: Object, loc: CommentLoc, code: string, github?: CommentContextGitHub diff --git a/src/extractors/exported.js b/src/extractors/exported.js index 6d36eea6b..b8b724529 100644 --- a/src/extractors/exported.js +++ b/src/extractors/exported.js @@ -151,14 +151,17 @@ function traverseExportedSubtree(path, data, addComments, overrideName) { } addComments(data, attachCommentPath, overrideName); - path = findTarget(path); + let target = findTarget(path); + if (!target) { + return; + } - if (t.isVariableDeclarator(path) && path.has('init')) { - path = path.get('init'); + if (t.isVariableDeclarator(target) && target.has('init')) { + target = target.get('init'); } - if (path.isClass() || path.isObjectExpression()) { - path.traverse({ + if (target.isClass() || target.isObjectExpression()) { + target.traverse({ Property(path) { addComments(data, path); path.skip(); diff --git a/src/infer/finders.js b/src/infer/finders.js index 645c22b86..f85471b08 100644 --- a/src/infer/finders.js +++ b/src/infer/finders.js @@ -10,7 +10,7 @@ var t = require('babel-types'); * @returns {?Object} ast path, if one is found. * @private */ -function findTarget(path: Object) { +function findTarget(path: ?Object) { if (!path) { return path; } diff --git a/src/infer/membership.js b/src/infer/membership.js index 2b2f852da..f887109cd 100644 --- a/src/infer/membership.js +++ b/src/infer/membership.js @@ -241,32 +241,15 @@ module.exports = function() { return comment; } - function shouldSkipInference(comment: Comment): boolean { - // If someone uses the @name tag, they explicitly ask for inference - // to be skipped. - if (comment.tags.some(tag => tag.title === 'name')) { - return true; - } - + return function inferMembership(comment: Comment) { // Lends tags are go-betweens that let people reassign membership // in bulk: they themselves don't get an inference step if (comment.lends) { - return true; - } - - // If this chunk doesn't have code attached, like if it was the result - // of a polyglot parse, don't try to infer anything. - if (!comment.context.ast) { - return true; + return comment; } - return false; - } - - return function inferMembership(comment: Comment) { - // First skip inference if the user indicates it or if it isn't possible. - if (shouldSkipInference(comment)) { - return comment; + if (comment.kind === 'module') { + currentModule = comment; } // If someone explicitly specifies the parent of this chunk, don't @@ -275,11 +258,12 @@ module.exports = function() { return normalizeMemberof(comment); } - if (comment.kind === 'module') { - currentModule = comment; - } - var path = comment.context.ast; + // If this chunk doesn't have code attached, like if it was the result + // of a polyglot parse, don't try to infer anything. + if (!path) { + return comment; + } // INFERENCE =============================================================== // Deal with an oddity of espree: the jsdoc comment is attached to a different diff --git a/src/infer/params.js b/src/infer/params.js index cb9791000..4fa84a7f6 100644 --- a/src/infer/params.js +++ b/src/infer/params.js @@ -14,6 +14,9 @@ import flowDoctrine from '../flow_doctrine'; */ function inferParams(comment: Comment) { var path = finders.findTarget(comment.context.ast); + if (!path) { + return comment; + } // In case of `/** */ var x = function () {}` findTarget returns // the declarator. @@ -277,7 +280,9 @@ function mergeTopNodes(inferred, explicit) { var errors = explicitTagsWithoutInference.map(tag => { return { - message: `An explicit parameter named ${tag.name || ''} was specified but didn't match ` + + message: + `An explicit parameter named ${tag.name || + ''} was specified but didn't match ` + `inferred information ${Array.from(inferredNames).join(', ')}`, commentLineNumber: tag.lineNumber }; diff --git a/src/infer/return.js b/src/infer/return.js index e1bc147e5..bd22c9f00 100644 --- a/src/infer/return.js +++ b/src/infer/return.js @@ -21,6 +21,9 @@ function inferReturn(comment: Comment) { } var path = findTarget(comment.context.ast); var fn = path && path.node; + if (!fn) { + return comment; + } // In case of `/** */ var x = function () {}` findTarget returns // the declarator. diff --git a/src/output/html.js b/src/output/html.js index 35485702d..0c004889e 100644 --- a/src/output/html.js +++ b/src/output/html.js @@ -6,7 +6,7 @@ var mergeConfig = require('../merge_config'); /** * Formats documentation as HTML. * - * @param comments parsed comments + * @param {Array} comments parsed comments * @param {Object} config Options that can customize the output * @param {string} [config.theme='default_theme'] Name of a module used for an HTML theme. * @returns {Promise>} Promise with results diff --git a/src/output/json.js b/src/output/json.js index a210c6362..01d5248d8 100644 --- a/src/output/json.js +++ b/src/output/json.js @@ -5,7 +5,8 @@ import { walk } from '../walk'; /** * Formats documentation as a JSON string. * - * @param comments parsed comments + * @param {Array} comments parsed comments + * @returns {Promise} * @name formats.json * @public * @example diff --git a/src/parse.js b/src/parse.js index c1cef57b7..27068d89d 100644 --- a/src/parse.js +++ b/src/parse.js @@ -622,6 +622,12 @@ function parseJSDoc(comment: string, loc: ?Object, context: ?Object): Comment { } }); + // Using the @name tag, or any other tag that sets the name of a comment, + // disconnects the comment from its surrounding code. + if (context && result.name) { + delete context.ast; + } + return result; }