From 6998a05939280e44a394cd82309d2a9ff02639b7 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Wed, 23 Nov 2016 16:47:38 -0500 Subject: [PATCH 001/583] chore(dependencies): Update dependency ranges for all that can be seamlessly upgraded (#617) We're pinning certain dependencies, still, like parse-filepath, because they alter documentation.js's behavior: those will need further investigation --- package.json | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/package.json b/package.json index 1d58fe902..c2f392ded 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "documentation": "./bin/documentation.js" }, "dependencies": { - "ansi-html": "0.0.5", + "ansi-html": "^0.0.6", "babel-core": "^6.17.0", "babel-generator": "6.19.0", "babel-plugin-system-import-transformer": "2.4.0", @@ -24,8 +24,7 @@ "concat-stream": "^1.5.0", "debounce": "^1.0.0", "disparity": "^2.0.0", - "doctrine": "^1.5.0", - "events": "^1.1.0", + "doctrine": "^2.0.0", "extend": "^3.0.0", "get-comments": "^1.0.1", "git-url-parse": "^6.0.1", @@ -47,7 +46,7 @@ "standard-changelog": "0.0.1", "stream-array": "^1.1.0", "strip-json-comments": "^2.0.0", - "tiny-lr": "^0.2.1", + "tiny-lr": "^1.0.3", "unist-builder": "^1.0.0", "unist-util-visit": "^1.0.1", "vfile": "^2.0.0", @@ -62,12 +61,12 @@ "cz-conventional-changelog": "1.2.0", "documentation-schema": "0.0.1", "eslint": "^3.1.0", - "fs-extra": "^0.30.0", + "fs-extra": "^1.0.0", "glob": "^7.0.0", "json-schema": "0.2.3", "mock-fs": "^3.5.0", - "tap": "^7.1.2", - "tmp": "0.0.29" + "tap": "^8.0.0", + "tmp": "^0.0.29" }, "keywords": [ "documentation", From f9ddb9cd29383dc95849679cf44915ee1ac1fe35 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Fri, 25 Nov 2016 18:31:21 -0500 Subject: [PATCH 002/583] Output typedef content in Markdown and HTML. Fixes #359 (#619) --- default_theme/section._ | 7 + lib/output/markdown_ast.js | 9 + test/fixture/document-exported.output.md | 8 + test/fixture/document-exported.output.md.json | 80 ++++ test/fixture/html/nested.config-output.html | 34 ++ test/fixture/html/nested.output.files | 34 ++ .../optional-record-field-type.output.md | 2 + .../optional-record-field-type.output.md.json | 55 +++ test/fixture/sync/flow-types.input.js | 10 + test/fixture/sync/flow-types.output.json | 212 +++++++++ test/fixture/sync/flow-types.output.md | 18 + test/fixture/sync/flow-types.output.md.json | 407 ++++++++++++++++++ test/fixture/sync/typedef.output.md | 2 + test/fixture/sync/typedef.output.md.json | 20 + 14 files changed, 898 insertions(+) diff --git a/default_theme/section._ b/default_theme/section._ index 06f7bd2f4..23ce87892 100644 --- a/default_theme/section._ +++ b/default_theme/section._ @@ -19,6 +19,13 @@
<%= signature(section) %>
+ <% if (section.type) { %> +

+ Type: + <%= formatType(section.type) %> +

+ <% } %> + <% if (section.augments) { %>

Extends diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js index 13080416e..76d0df055 100644 --- a/lib/output/markdown_ast.js +++ b/lib/output/markdown_ast.js @@ -43,6 +43,14 @@ function commentsToAST(comments, options, callback) { */ function generate(depth, comment) { + function typeSection(comment) { + return comment.type && u('paragraph', [ + u('text', 'Type: ') + ].concat( + formatType(comment.type) + )); + } + function paramList(params) { return u('list', { ordered: false }, params.map(function (param) { return u('listItem', [ @@ -176,6 +184,7 @@ function commentsToAST(comments, options, callback) { .concat(githubLink(comment)) .concat(augmentsLink(comment)) .concat(comment.description ? comment.description.children : []) + .concat(typeSection(comment)) .concat(paramSection(comment)) .concat(propertySection(comment)) .concat(examplesSection(comment)) diff --git a/test/fixture/document-exported.output.md b/test/fixture/document-exported.output.md index 050ee4474..e6743fe0c 100644 --- a/test/fixture/document-exported.output.md +++ b/test/fixture/document-exported.output.md @@ -34,6 +34,8 @@ # T5 +Type: [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) + # y2Default # y4 @@ -68,10 +70,16 @@ Returns **void** # T +Type: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) + # T2 +Type: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) + # T4 +Type: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) + # f4 **Parameters** diff --git a/test/fixture/document-exported.output.md.json b/test/fixture/document-exported.output.md.json index ea3cff981..4ccd7a6af 100644 --- a/test/fixture/document-exported.output.md.json +++ b/test/fixture/document-exported.output.md.json @@ -226,6 +226,26 @@ } ] }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", + "type": "link", + "children": [ + { + "type": "text", + "value": "boolean" + } + ] + } + ] + }, { "depth": 1, "type": "heading", @@ -483,6 +503,26 @@ } ] }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + } + ] + }, { "depth": 1, "type": "heading", @@ -493,6 +533,26 @@ } ] }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + } + ] + }, { "depth": 1, "type": "heading", @@ -503,6 +563,26 @@ } ] }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + } + ] + }, { "depth": 1, "type": "heading", diff --git a/test/fixture/html/nested.config-output.html b/test/fixture/html/nested.config-output.html index 470ecf382..a31473185 100644 --- a/test/fixture/html/nested.config-output.html +++ b/test/fixture/html/nested.config-output.html @@ -258,6 +258,8 @@

new Klass(foo: any)
+ +

Extends @@ -321,6 +323,8 @@

+ + @@ -396,6 +400,8 @@

+ + @@ -462,6 +468,8 @@

+ + @@ -538,6 +546,8 @@

+ + @@ -612,6 +622,8 @@

+ + @@ -657,6 +669,8 @@

+ + @@ -710,6 +724,8 @@

+ + @@ -770,6 +786,8 @@

+ + @@ -875,6 +893,8 @@

+ + @@ -949,6 +969,8 @@

+ + @@ -1003,6 +1025,8 @@

+ + @@ -1072,6 +1096,8 @@

+ + @@ -1125,6 +1151,8 @@

+ + @@ -1167,6 +1195,8 @@

+ + @@ -1220,6 +1250,8 @@

customStreams
+ + @@ -1262,6 +1294,8 @@

+ + diff --git a/test/fixture/html/nested.output.files b/test/fixture/html/nested.output.files index 9c9e5725a..c9a7449d0 100644 --- a/test/fixture/html/nested.output.files +++ b/test/fixture/html/nested.output.files @@ -220,6 +220,8 @@
new Klass(foo: any)
+ +

Extends @@ -283,6 +285,8 @@ This is a [link to something that does not exist]DoesNot + + @@ -424,6 +430,8 @@ the referenced class type

+ + @@ -500,6 +508,8 @@ the referenced class type

+ + @@ -574,6 +584,8 @@ k.isArrayOfBuffers(); + + @@ -619,6 +631,8 @@ k.isArrayOfBuffers(); + + @@ -672,6 +686,8 @@ k.isArrayOfBuffers(); + + @@ -732,6 +748,8 @@ k.isArrayOfBuffers(); + + @@ -837,6 +855,8 @@ k.isArrayOfBuffers(); + + @@ -911,6 +931,8 @@ like a klass

+ + @@ -965,6 +987,8 @@ like a klass

+ + @@ -1034,6 +1058,8 @@ like a klass. This needs a klass. This needs a klass. This needs a klass. This needs a klass. This needs a Bar) {} + +/** My type */ +export type T = number; + +/** + * Define my object API + */ +export type SomeObjectAPI = { + method: (param: string) => boolean +} diff --git a/test/fixture/sync/flow-types.output.json b/test/fixture/sync/flow-types.output.json index 35304499f..6dbe4b0bf 100644 --- a/test/fixture/sync/flow-types.output.json +++ b/test/fixture/sync/flow-types.output.json @@ -749,6 +749,101 @@ ], "namespace": "T" }, + { + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "My type", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 8, + "offset": 7 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 8, + "offset": 7 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 8, + "offset": 7 + } + } + }, + "tags": [], + "loc": { + "start": { + "line": 64, + "column": 0 + }, + "end": { + "line": 64, + "column": 14 + } + }, + "context": { + "loc": { + "start": { + "line": 65, + "column": 0 + }, + "end": { + "line": 65, + "column": 23 + } + } + }, + "errors": [], + "name": "T", + "kind": "typedef", + "type": { + "type": "NameExpression", + "name": "number" + }, + "members": { + "instance": [], + "static": [] + }, + "path": [ + { + "name": "T", + "kind": "typedef" + } + ], + "namespace": "T" + }, { "description": { "type": "root", @@ -1210,5 +1305,122 @@ } ], "namespace": "objectParamFn" + }, + { + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Define my object API", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + } + } + }, + "tags": [], + "loc": { + "start": { + "line": 67, + "column": 0 + }, + "end": { + "line": 69, + "column": 3 + } + }, + "context": { + "loc": { + "start": { + "line": 70, + "column": 0 + }, + "end": { + "line": 72, + "column": 1 + } + } + }, + "errors": [], + "name": "SomeObjectAPI", + "kind": "typedef", + "type": { + "type": "RecordType", + "fields": [ + { + "type": "FieldType", + "key": "method", + "value": { + "type": "FunctionType", + "params": [ + { + "type": "ParameterType", + "name": "param", + "expression": { + "type": "NameExpression", + "name": "string" + } + } + ], + "result": { + "type": "NameExpression", + "name": "boolean" + } + } + } + ] + }, + "members": { + "instance": [], + "static": [] + }, + "path": [ + { + "name": "SomeObjectAPI", + "kind": "typedef" + } + ], + "namespace": "SomeObjectAPI" } ] \ No newline at end of file diff --git a/test/fixture/sync/flow-types.output.md b/test/fixture/sync/flow-types.output.md index ae907df12..14d68bd2b 100644 --- a/test/fixture/sync/flow-types.output.md +++ b/test/fixture/sync/flow-types.output.md @@ -19,6 +19,8 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer A 2D point. +Type: {x: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), y: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), rgb: {hex: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)}, props: {radius: {x: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)}}} + **Properties** - `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** this is a prop @@ -33,6 +35,8 @@ A 2D point. A type with entirely derived properties +Type: {x: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), y: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), z: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?} + **Properties** - `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** @@ -43,6 +47,14 @@ A type with entirely derived properties Just an alias for an array of strings +Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> + +# T + +My type + +Type: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) + # veryImportantTransform Very Important Transform @@ -77,3 +89,9 @@ hi **Parameters** - `x` **function (y: Foo): Bar** + +# SomeObjectAPI + +Define my object API + +Type: {method: function (param: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)): [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)} diff --git a/test/fixture/sync/flow-types.output.md.json b/test/fixture/sync/flow-types.output.md.json index 0a303ae91..283ad8ae5 100644 --- a/test/fixture/sync/flow-types.output.md.json +++ b/test/fixture/sync/flow-types.output.md.json @@ -383,6 +383,131 @@ "indent": [] } }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "type": "text", + "value": "{" + }, + { + "type": "text", + "value": "x: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": ", " + }, + { + "type": "text", + "value": "y: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": ", " + }, + { + "type": "text", + "value": "rgb: " + }, + { + "type": "text", + "value": "{" + }, + { + "type": "text", + "value": "hex: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + }, + { + "type": "text", + "value": "}" + }, + { + "type": "text", + "value": ", " + }, + { + "type": "text", + "value": "props: " + }, + { + "type": "text", + "value": "{" + }, + { + "type": "text", + "value": "radius: " + }, + { + "type": "text", + "value": "{" + }, + { + "type": "text", + "value": "x: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": "}" + }, + { + "type": "text", + "value": "}" + }, + { + "type": "text", + "value": "}" + } + ] + }, { "type": "strong", "children": [ @@ -810,6 +935,80 @@ "indent": [] } }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "type": "text", + "value": "{" + }, + { + "type": "text", + "value": "x: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": ", " + }, + { + "type": "text", + "value": "y: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": ", " + }, + { + "type": "text", + "value": "z: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": "?" + }, + { + "type": "text", + "value": "}" + } + ] + }, { "type": "strong", "children": [ @@ -988,6 +1187,110 @@ "indent": [] } }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", + "type": "link", + "children": [ + { + "type": "text", + "value": "Array" + } + ] + }, + { + "type": "text", + "value": "<" + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + }, + { + "type": "text", + "value": ">" + } + ] + }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "T" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "My type", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 8, + "offset": 7 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 8, + "offset": 7 + }, + "indent": [] + } + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + } + ] + }, { "depth": 1, "type": "heading", @@ -1532,6 +1835,110 @@ ] } ] + }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "SomeObjectAPI" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Define my object API", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "type": "text", + "value": "{" + }, + { + "type": "text", + "value": "method: " + }, + { + "type": "text", + "value": "function (" + }, + { + "type": "text", + "value": "param: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + }, + { + "type": "text", + "value": ")" + }, + { + "type": "text", + "value": ": " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", + "type": "link", + "children": [ + { + "type": "text", + "value": "boolean" + } + ] + }, + { + "type": "text", + "value": "}" + } + ] } ] } \ No newline at end of file diff --git a/test/fixture/sync/typedef.output.md b/test/fixture/sync/typedef.output.md index e2ed3269d..35d1486f9 100644 --- a/test/fixture/sync/typedef.output.md +++ b/test/fixture/sync/typedef.output.md @@ -4,6 +4,8 @@ A type definition. +Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) + **Properties** - `prop1` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** one property diff --git a/test/fixture/sync/typedef.output.md.json b/test/fixture/sync/typedef.output.md.json index cefb610d6..46571272d 100644 --- a/test/fixture/sync/typedef.output.md.json +++ b/test/fixture/sync/typedef.output.md.json @@ -50,6 +50,26 @@ "indent": [] } }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Type: " + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object", + "type": "link", + "children": [ + { + "type": "text", + "value": "Object" + } + ] + } + ] + }, { "type": "strong", "children": [ From 8b040291384e5e99f460a9d57f5f44d3cbb175f7 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Fri, 25 Nov 2016 18:35:11 -0500 Subject: [PATCH 003/583] feat(output): Display type information for typedefs in Markdown and HTML This is a follow-up commit because I didn't format the original commit message properly and didn't want to ammend master. --- default_theme/section._ | 2 -- test/fixture/html/nested.config-output.html | 34 --------------------- test/fixture/html/nested.output.files | 34 --------------------- 3 files changed, 70 deletions(-) diff --git a/default_theme/section._ b/default_theme/section._ index 23ce87892..a75159b83 100644 --- a/default_theme/section._ +++ b/default_theme/section._ @@ -18,14 +18,12 @@ <%= md(section.description) %>
<%= signature(section) %>
- <% if (section.type) { %>

Type: <%= formatType(section.type) %>

<% } %> - <% if (section.augments) { %>

Extends diff --git a/test/fixture/html/nested.config-output.html b/test/fixture/html/nested.config-output.html index a31473185..4250860a2 100644 --- a/test/fixture/html/nested.config-output.html +++ b/test/fixture/html/nested.config-output.html @@ -256,9 +256,7 @@

new Klass(foo: any)
- -

Extends @@ -319,9 +317,7 @@

isClass(other: Object, also: any): boolean
- - @@ -396,9 +392,7 @@

isWeird(other: Weird): boolean
- - @@ -464,9 +458,7 @@

isBuffer(buf: (Buffer | string), size: number?): boolean
- - @@ -542,9 +534,7 @@

isArrayOfBuffers(buffers: Array<Buffer>): number
- - @@ -618,9 +608,7 @@

MAGIC_NUMBER
- - @@ -665,9 +653,7 @@

event
- - @@ -720,9 +706,7 @@

getFoo(): Number
- - @@ -782,9 +766,7 @@

withOptions(options: Object, otherOptions: number?)
- - @@ -889,9 +871,7 @@

CustomError
- - @@ -965,9 +945,7 @@

bar(): Klass
- - @@ -1021,9 +999,7 @@

bar(toys: ...Number): undefined
- - @@ -1092,9 +1068,7 @@

bar(): undefined
- - @@ -1148,9 +1122,7 @@

new Foo()
- - @@ -1191,9 +1163,7 @@

bar
- - @@ -1249,9 +1219,7 @@

customStreams
- - @@ -1290,9 +1258,7 @@

new passthrough()
- - diff --git a/test/fixture/html/nested.output.files b/test/fixture/html/nested.output.files index c9a7449d0..c032a4005 100644 --- a/test/fixture/html/nested.output.files +++ b/test/fixture/html/nested.output.files @@ -218,9 +218,7 @@
new Klass(foo: any)
- -

Extends @@ -281,9 +279,7 @@ This is a [link to something that does not exist]DoesNotisClass(other: Object, also: any): boolean - - @@ -358,9 +354,7 @@ the referenced class type

isWeird(other: Weird): boolean
- - @@ -426,9 +420,7 @@ the referenced class type

isBuffer(buf: (Buffer | string), size: number?): boolean
- - @@ -504,9 +496,7 @@ the referenced class type

isArrayOfBuffers(buffers: Array<Buffer>): number
- - @@ -580,9 +570,7 @@ k.isArrayOfBuffers();
MAGIC_NUMBER
- - @@ -627,9 +615,7 @@ k.isArrayOfBuffers();
event
- - @@ -682,9 +668,7 @@ k.isArrayOfBuffers();
getFoo(): Number
- - @@ -744,9 +728,7 @@ k.isArrayOfBuffers();
withOptions(options: Object, otherOptions: number?)
- - @@ -851,9 +833,7 @@ k.isArrayOfBuffers();
CustomError
- - @@ -927,9 +907,7 @@ like a klass

bar(): Klass
- - @@ -983,9 +961,7 @@ like a klass

bar(toys: ...Number): undefined
- - @@ -1054,9 +1030,7 @@ like a klass. This needs a undefined - - @@ -1110,9 +1084,7 @@ like a klass. This needs a klass. This needs a klass. This needs a klass. This needs a Date: Sat, 3 Dec 2016 09:30:24 -0800 Subject: [PATCH 007/583] fix(extractors): Document export default value (#623) With `--document-exported` we used to only support ```js export default Declaration ``` and ```js export default IdentifierExpression ``` With this change we generate a comment for all default exports. Fixes #543 --- lib/extractors/exported.js | 7 +- ...nt-exported-export-default-object.input.js | 5 ++ ...exported-export-default-object.output.json | 78 +++++++++++++++++++ ...t-exported-export-default-object.output.md | 5 ++ ...orted-export-default-object.output.md.json | 29 +++++++ ...ent-exported-export-default-value.input.js | 3 + ...-exported-export-default-value.output.json | 40 ++++++++++ ...nt-exported-export-default-value.output.md | 3 + ...ported-export-default-value.output.md.json | 19 +++++ 9 files changed, 185 insertions(+), 4 deletions(-) create mode 100644 test/fixture/document-exported-export-default-object.input.js create mode 100644 test/fixture/document-exported-export-default-object.output.json create mode 100644 test/fixture/document-exported-export-default-object.output.md create mode 100644 test/fixture/document-exported-export-default-object.output.md.json create mode 100644 test/fixture/document-exported-export-default-value.input.js create mode 100644 test/fixture/document-exported-export-default-value.output.json create mode 100644 test/fixture/document-exported-export-default-value.output.md create mode 100644 test/fixture/document-exported-export-default-value.output.md.json diff --git a/lib/extractors/exported.js b/lib/extractors/exported.js index 6b39c3d3a..92d8a22a5 100644 --- a/lib/extractors/exported.js +++ b/lib/extractors/exported.js @@ -66,15 +66,14 @@ function walkExported(ast, data, addComment) { } if (path.isExportDefaultDeclaration()) { - if (declaration.isDeclaration()) { - traverseExportedSubtree(declaration, data, addComments); - return path.skip(); - } if (declaration.isIdentifier()) { var binding = declaration.scope.getBinding(declaration.node.name); traverseExportedSubtree(binding.path, data, addComments); return path.skip(); } + + traverseExportedSubtree(declaration, data, addComments); + return path.skip(); } if (t.isExportNamedDeclaration(path)) { diff --git a/test/fixture/document-exported-export-default-object.input.js b/test/fixture/document-exported-export-default-object.input.js new file mode 100644 index 000000000..01d62a0ee --- /dev/null +++ b/test/fixture/document-exported-export-default-object.input.js @@ -0,0 +1,5 @@ +// Options: {"documentExported": true} + +export default { + x: 42, +}; diff --git a/test/fixture/document-exported-export-default-object.output.json b/test/fixture/document-exported-export-default-object.output.json new file mode 100644 index 000000000..c85665602 --- /dev/null +++ b/test/fixture/document-exported-export-default-object.output.json @@ -0,0 +1,78 @@ +[ + { + "description": "", + "tags": [], + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 5, + "column": 2 + } + }, + "context": { + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 5, + "column": 2 + } + } + }, + "errors": [], + "name": "document-exported-export-default-object.input", + "members": { + "instance": [], + "static": [] + }, + "path": [ + { + "name": "document-exported-export-default-object.input" + } + ], + "namespace": "document-exported-export-default-object.input" + }, + { + "description": "", + "tags": [], + "loc": { + "start": { + "line": 4, + "column": 2 + }, + "end": { + "line": 4, + "column": 7 + } + }, + "context": { + "loc": { + "start": { + "line": 4, + "column": 2 + }, + "end": { + "line": 4, + "column": 7 + } + } + }, + "errors": [], + "name": "x", + "members": { + "instance": [], + "static": [] + }, + "path": [ + { + "name": "x" + } + ], + "namespace": "x" + } +] \ No newline at end of file diff --git a/test/fixture/document-exported-export-default-object.output.md b/test/fixture/document-exported-export-default-object.output.md new file mode 100644 index 000000000..4162bb1aa --- /dev/null +++ b/test/fixture/document-exported-export-default-object.output.md @@ -0,0 +1,5 @@ + + +# document-exported-export-default-object.input + +# x diff --git a/test/fixture/document-exported-export-default-object.output.md.json b/test/fixture/document-exported-export-default-object.output.md.json new file mode 100644 index 000000000..c1f4ca589 --- /dev/null +++ b/test/fixture/document-exported-export-default-object.output.md.json @@ -0,0 +1,29 @@ +{ + "type": "root", + "children": [ + { + "type": "html", + "value": "" + }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "document-exported-export-default-object.input" + } + ] + }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "x" + } + ] + } + ] +} \ No newline at end of file diff --git a/test/fixture/document-exported-export-default-value.input.js b/test/fixture/document-exported-export-default-value.input.js new file mode 100644 index 000000000..d9c98e434 --- /dev/null +++ b/test/fixture/document-exported-export-default-value.input.js @@ -0,0 +1,3 @@ +// Options: {"documentExported": true} + +export default 42; diff --git a/test/fixture/document-exported-export-default-value.output.json b/test/fixture/document-exported-export-default-value.output.json new file mode 100644 index 000000000..e15877f5d --- /dev/null +++ b/test/fixture/document-exported-export-default-value.output.json @@ -0,0 +1,40 @@ +[ + { + "description": "", + "tags": [], + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "context": { + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 18 + } + } + }, + "errors": [], + "name": "document-exported-export-default-value.input", + "members": { + "instance": [], + "static": [] + }, + "path": [ + { + "name": "document-exported-export-default-value.input" + } + ], + "namespace": "document-exported-export-default-value.input" + } +] \ No newline at end of file diff --git a/test/fixture/document-exported-export-default-value.output.md b/test/fixture/document-exported-export-default-value.output.md new file mode 100644 index 000000000..bf6fea702 --- /dev/null +++ b/test/fixture/document-exported-export-default-value.output.md @@ -0,0 +1,3 @@ + + +# document-exported-export-default-value.input diff --git a/test/fixture/document-exported-export-default-value.output.md.json b/test/fixture/document-exported-export-default-value.output.md.json new file mode 100644 index 000000000..22f2087f3 --- /dev/null +++ b/test/fixture/document-exported-export-default-value.output.md.json @@ -0,0 +1,19 @@ +{ + "type": "root", + "children": [ + { + "type": "html", + "value": "" + }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "document-exported-export-default-value.input" + } + ] + } + ] +} \ No newline at end of file From 89fb67f907fd4ab4934895fd9a8e3ece3b0cc05a Mon Sep 17 00:00:00 2001 From: Friedel Ziegelmayer Date: Mon, 5 Dec 2016 21:00:10 +0100 Subject: [PATCH 008/583] feat(build): load passed in config option (#625) * feat(build): load passed in config option Fixes #https://github.com/documentationjs/gulp-documentation/issues/27 * refactor(build): streamline loadConfig path --- index.js | 30 ++++++++++++++++++++++++++--- lib/commands/build.js | 15 ++++++++------- lib/commands/shared_options.js | 6 +----- test/fixture/class.config.output.md | 29 ++++++++++++++++++++++++++++ test/fixture/simple.config.yml | 4 ++++ test/test.js | 16 +++++++++++++++ 6 files changed, 85 insertions(+), 15 deletions(-) create mode 100644 test/fixture/class.config.output.md create mode 100644 test/fixture/simple.config.yml diff --git a/index.js b/index.js index d56540339..c962c0824 100644 --- a/index.js +++ b/index.js @@ -24,7 +24,8 @@ var fs = require('fs'), formatLint = require('./lib/lint').formatLint, garbageCollect = require('./lib/garbage_collect'), lintComments = require('./lib/lint').lintComments, - markdownAST = require('./lib/output/markdown_ast'); + markdownAST = require('./lib/output/markdown_ast'), + loadConfig = require('./lib/load_config'); /** * Build a pipeline of comment handlers. @@ -64,6 +65,19 @@ function expandInputs(indexes, options, callback) { inputFn(indexes, options, callback); } +/** + * Given an options object, it expands the `config` field + * if it exists. + * + * @param {Object} options - options to process + * @returns {undefined} + */ +function expandConfig(options) { + if (options && typeof options.config === 'string') { + Object.assign(options, loadConfig(options.config)); + } +} + /** * Generate JavaScript documentation as a list of parsed JSDoc * comments, given a root file as a path. @@ -114,6 +128,8 @@ function expandInputs(indexes, options, callback) { function build(indexes, options, callback) { options = options || {}; + expandConfig(options); + if (typeof indexes === 'string') { indexes = [indexes]; } @@ -122,11 +138,14 @@ function build(indexes, options, callback) { if (error) { return callback(error); } + + var result; try { - callback(null, buildSync(inputs, options)); + result = buildSync(inputs, options); } catch (e) { - callback(e); + return callback(e); } + callback(null, result); }); } @@ -137,6 +156,7 @@ function build(indexes, options, callback) { * * @param {Array} indexes files to process * @param {Object} options options + * @param {string} config path to configuration file to load * @param {Array} options.external a string regex / glob match pattern * that defines what external modules will be whitelisted and included in the * generated documentation. @@ -172,6 +192,8 @@ function buildSync(indexes, options) { options = options || {}; options.hljs = options.hljs || {}; + expandConfig(options); + if (!options.access) { options.access = ['public', 'undefined', 'protected']; } @@ -259,6 +281,8 @@ function buildSync(indexes, options) { function lint(indexes, options, callback) { options = options || {}; + expandConfig(options); + if (typeof indexes === 'string') { indexes = [indexes]; } diff --git a/lib/commands/build.js b/lib/commands/build.js index 6d724c2f1..4fd6fe74c 100644 --- a/lib/commands/build.js +++ b/lib/commands/build.js @@ -49,13 +49,6 @@ module.exports.handler = function build(argv, callback) { if (argv.f === 'html' && argv.o === 'stdout') { throw new Error('The HTML output mode requires a destination directory set with -o'); } - var formatterOptions = { - name: argv.name || (argv.package || {}).name, - version: argv['project-version'] || (argv.package || {}).version, - theme: argv.theme, - paths: argv.paths, - hljs: argv.hljs || {} - }; var generator = documentation.build .bind(null, argv.input, argv, onDocumented); @@ -68,6 +61,14 @@ module.exports.handler = function build(argv, callback) { throw err; } + var formatterOptions = { + name: argv.name || (argv.package || {}).name, + version: argv['project-version'] || (argv.package || {}).version, + theme: argv.theme, + paths: argv.paths, + hljs: argv.hljs || {} + }; + documentation.formats[argv.format](comments, formatterOptions, onFormatted); } diff --git a/lib/commands/shared_options.js b/lib/commands/shared_options.js index fdf5924af..5550eb417 100644 --- a/lib/commands/shared_options.js +++ b/lib/commands/shared_options.js @@ -1,5 +1,4 @@ var path = require('path'); -var loadConfig = require('../load_config'); /** * Adds shared options to any command that runs documentation @@ -16,12 +15,9 @@ module.exports.sharedInputOptions = { type: 'boolean' }, 'config': { - config: true, describe: 'configuration file. an array defining explicit sort order', alias: 'c', - configParser: function (configPath) { - return loadConfig(configPath); - } + type: 'string' }, 'external': { describe: 'a string / glob match pattern that defines which external ' + diff --git a/test/fixture/class.config.output.md b/test/fixture/class.config.output.md new file mode 100644 index 000000000..3f23e0ba3 --- /dev/null +++ b/test/fixture/class.config.output.md @@ -0,0 +1,29 @@ + + +# MyClass + +This is my class, a demo thing. + +**Properties** + +- `howMany` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** how many things it contains + +## getFoo + +Get the number 42 + +**Parameters** + +- `getIt` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether to get the number + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** forty-two + +## getUndefined + +Get undefined + +Returns **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** does not return anything. + +# Hello + +World diff --git a/test/fixture/simple.config.yml b/test/fixture/simple.config.yml new file mode 100644 index 000000000..cbf17ca9b --- /dev/null +++ b/test/fixture/simple.config.yml @@ -0,0 +1,4 @@ +toc: + - MyClass + - name: Hello + description: World diff --git a/test/test.js b/test/test.js index 91e561d0b..74412f9bb 100644 --- a/test/test.js +++ b/test/test.js @@ -250,6 +250,22 @@ test('highlightAuto md output', function (t) { }); }); +test('config', function (t) { + var file = path.join(__dirname, 'fixture', 'class.input.js'); + var result = fs.readFileSync(path.join(__dirname, 'fixture', 'class.config.output.md')).toString(); + documentation.build([file], { + config: path.join(__dirname, 'fixture', 'simple.config.yml') + }, function (err, out) { + t.ifError(err); + outputMarkdown(out, {}, function (err, md) { + t.ifError(err); + + t.equal(md, result, 'rendered markdown is equal'); + t.end(); + }); + }); +}); + test('multi-file input', function (t) { documentation.build([ path.join(__dirname, 'fixture', 'simple.input.js'), From 11fef7d8588c98ec94f17ec442065d4803a2420d Mon Sep 17 00:00:00 2001 From: Denis Andrejew Date: Wed, 7 Dec 2016 03:08:46 +0000 Subject: [PATCH 009/583] docs(install): reiterate installation directions in getting started crucial since home page links to GETTING_STARTED.md, without first showing any installation instructions -- those are currently only found in the README.md / GH repo landing page. --- docs/GETTING_STARTED.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index d4918be07..2543dd3ca 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -1,6 +1,6 @@ # Getting Started -Assuming that you've installed the `documentation` application, how do you +Assuming that you've installed the `documentation` application (`npm install -g documentation` if you haven't), how do you get started actually using it to document your code? Traditionally you might write documentation by creating a new Markdown From ab16a208720f978172676de1659a34a2bee4ec4a Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Wed, 7 Dec 2016 17:29:06 -0500 Subject: [PATCH 010/583] fix(bin): Remove dead code in documentation.js command (#627) --- bin/documentation.js | 5 ----- 1 file changed, 5 deletions(-) diff --git a/bin/documentation.js b/bin/documentation.js index e1c6a918a..886e2ef18 100755 --- a/bin/documentation.js +++ b/bin/documentation.js @@ -50,8 +50,3 @@ if (!argv._handled) { yargs.showHelp('error'); process.exit(1); } - - -if (!yargs.argv._.length) { - yargs.showHelp(); -} From 73ba79b37acd78741e7b01500a58dd77390e7317 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Wed, 7 Dec 2016 17:38:36 -0500 Subject: [PATCH 011/583] Changelog and package for beta16 --- CHANGELOG.md | 18 ++++++++++++++++++ package.json | 2 +- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d1e544db..0b889b0fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,21 @@ + +# [4.0.0-beta16](https://github.com/documentationjs/documentation/compare/v4.0.0-beta15...v4.0.0-beta16) (2016-12-07) + + +### Bug Fixes + +* **bin:** Remove dead code in documentation.js command (#627) ([ab16a20](https://github.com/documentationjs/documentation/commit/ab16a20)) +* **extractors:** Document export default value (#623) ([363a108](https://github.com/documentationjs/documentation/commit/363a108)), closes [#543](https://github.com/documentationjs/documentation/issues/543) +* **parser:** Avoid error about deoptimization on very large files (#621) ([846ab94](https://github.com/documentationjs/documentation/commit/846ab94)) + +### Features + +* **build:** load passed in config option (#625) ([89fb67f](https://github.com/documentationjs/documentation/commit/89fb67f)) +* **output:** Display type information for typedefs in Markdown and HTML ([8b04029](https://github.com/documentationjs/documentation/commit/8b04029)) + + + + # [4.0.0-beta15](https://github.com/documentationjs/documentation/compare/v4.0.0-beta14...v4.0.0-beta15) (2016-11-23) diff --git a/package.json b/package.json index c2f392ded..a81a4facb 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "documentation", "description": "a documentation generator", - "version": "4.0.0-beta15", + "version": "4.0.0-beta16", "author": "Tom MacWright", "bin": { "documentation": "./bin/documentation.js" From f1e0267e7ceee5f64be8abe8ba427f8b5186fd67 Mon Sep 17 00:00:00 2001 From: Friedel Ziegelmayer Date: Thu, 8 Dec 2016 17:59:26 +0100 Subject: [PATCH 012/583] fix(hierarchy): collect events from static and instance members (#628) Fixes #486 --- lib/hierarchy.js | 30 ++++- test/fixture/_external-deps-included.json | 9 +- test/fixture/_multi-file-input.json | 6 +- test/fixture/boolean-literal-type.output.json | 3 +- test/fixture/class.output.json | 6 +- ...exported-export-default-object.output.json | 6 +- ...-exported-export-default-value.output.json | 3 +- test/fixture/document-exported.output.json | 84 ++++++++----- test/fixture/es6-class.output.json | 9 +- test/fixture/es6-default2.output.json | 3 +- test/fixture/es6-import.output.json | 9 +- test/fixture/es6.output.json | 57 ++++++--- test/fixture/event.output.json | 3 +- test/fixture/example-caption.output.json | 3 +- test/fixture/external.output.json | 3 +- test/fixture/factory.output.json | 9 +- test/fixture/html/nested.config-output.html | 113 ++++++++++-------- test/fixture/html/nested.output.files | 113 ++++++++++-------- test/fixture/infer-params.output.json | 6 +- test/fixture/infer-private.output.json | 3 +- test/fixture/inheritance.output.json | 6 +- test/fixture/inline-link.output.json | 6 +- test/fixture/internal.output.json | 3 +- test/fixture/literal_types.output.json | 6 +- test/fixture/memberedclass.output.json | 6 +- test/fixture/merge-infered-type.output.json | 3 +- test/fixture/multisignature.output.json | 6 +- test/fixture/nearby_params.output.json | 3 +- test/fixture/nest_params.output.json | 6 +- .../newline-in-description.output.json | 3 +- test/fixture/no-name.output.json | 3 +- .../optional-record-field-type.output.json | 3 +- test/fixture/params.output.json | 24 ++-- test/fixture/polyglot/blend.json | 3 +- test/fixture/react-jsx.output.json | 3 +- test/fixture/simple-hashbang.output.json | 3 +- test/fixture/simple-two.output.json | 3 +- test/fixture/simple.output.github.json | 3 +- test/fixture/simple.output.json | 3 +- test/fixture/sort-order-alpha.output.json | 30 +++-- test/fixture/sorting/output.json | 9 +- test/fixture/string-literal-key.output.json | 6 +- test/fixture/sync/alias.output.json | 3 +- test/fixture/sync/empty-example.output.json | 3 +- test/fixture/sync/flow-types.output.json | 30 +++-- test/fixture/sync/lots-of-options.output.json | 3 +- test/fixture/sync/meta.output.json | 3 +- test/fixture/sync/multiexample.output.json | 3 +- test/fixture/sync/rename.output.json | 3 +- test/fixture/sync/throws.output.json | 3 +- test/fixture/sync/trailing-only.output.json | 3 +- test/fixture/sync/trailing.output.json | 9 +- test/fixture/sync/typedef.output.json | 3 +- test/fixture/system-import.output.json | 3 +- test/fixture/this-class.output.json | 9 +- test/fixture/type_application.output.json | 3 +- .../var-function-param-return.output.json | 3 +- test/lib/hierarchy.js | 1 - 58 files changed, 447 insertions(+), 257 deletions(-) diff --git a/lib/hierarchy.js b/lib/hierarchy.js index 702e5b5bb..a597fc770 100644 --- a/lib/hierarchy.js +++ b/lib/hierarchy.js @@ -1,5 +1,6 @@ 'use strict'; +var _ = require('lodash'); var hasOwnProperty = Object.prototype.hasOwnProperty; /** @@ -119,16 +120,24 @@ module.exports = function (comments) { comment.members[scope] = node.members[scope]; } + var events = comment.members.events || []; + var groups = []; + if (comment.members.instance.length) { - comment.members.events = comment.members.instance.filter(function (member) { - return member.kind === 'event'; - }); + groups = _.groupBy(comment.members.instance, isEvent); - comment.members.instance = comment.members.instance.filter(function (member) { - return member.kind !== 'event'; - }); + events = events.concat(groups[true] || []); + comment.members.instance = groups[false] || []; + } + + if (comment.members.static.length) { + groups = _.groupBy(comment.members.static, isEvent); + + events = events.concat(groups[true] || []); + comment.members.static = groups[false] || []; } + comment.members.events = events; comment.path = path.map(pick).concat(pick(comment)); @@ -168,3 +177,12 @@ module.exports = function (comments) { return toComments(root.members.static); }; + +/** + * Check if a given member object is of kind `event`. + * @param {Object} member - The member to check. + * @returns {boolean} `true` if it is of kind `event`, otherwise false. + */ +function isEvent(member) { + return member.kind === 'event'; +} diff --git a/test/fixture/_external-deps-included.json b/test/fixture/_external-deps-included.json index 779e67335..15b2c155d 100644 --- a/test/fixture/_external-deps-included.json +++ b/test/fixture/_external-deps-included.json @@ -114,7 +114,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -275,7 +276,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -436,7 +438,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/_multi-file-input.json b/test/fixture/_multi-file-input.json index 854a11638..dd227b807 100644 --- a/test/fixture/_multi-file-input.json +++ b/test/fixture/_multi-file-input.json @@ -232,7 +232,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -393,7 +394,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/boolean-literal-type.output.json b/test/fixture/boolean-literal-type.output.json index 2ea4eb916..51d31929a 100644 --- a/test/fixture/boolean-literal-type.output.json +++ b/test/fixture/boolean-literal-type.output.json @@ -66,7 +66,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/class.output.json b/test/fixture/class.output.json index c539e4535..49b3b81e0 100644 --- a/test/fixture/class.output.json +++ b/test/fixture/class.output.json @@ -385,7 +385,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -551,7 +552,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/document-exported-export-default-object.output.json b/test/fixture/document-exported-export-default-object.output.json index c85665602..03b839755 100644 --- a/test/fixture/document-exported-export-default-object.output.json +++ b/test/fixture/document-exported-export-default-object.output.json @@ -28,7 +28,8 @@ "name": "document-exported-export-default-object.input", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -66,7 +67,8 @@ "name": "x", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/document-exported-export-default-value.output.json b/test/fixture/document-exported-export-default-value.output.json index e15877f5d..baa003f74 100644 --- a/test/fixture/document-exported-export-default-value.output.json +++ b/test/fixture/document-exported-export-default-value.output.json @@ -28,7 +28,8 @@ "name": "document-exported-export-default-value.input", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/document-exported.output.json b/test/fixture/document-exported.output.json index b886f3cbc..29d6660e1 100644 --- a/test/fixture/document-exported.output.json +++ b/test/fixture/document-exported.output.json @@ -61,7 +61,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -125,7 +126,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -197,7 +199,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -244,7 +247,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -298,7 +302,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -347,7 +352,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -394,7 +400,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -448,7 +455,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -508,7 +516,8 @@ }, "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -547,7 +556,8 @@ "name": "y2Default", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -655,7 +665,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -726,7 +737,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -771,7 +783,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -785,7 +798,8 @@ ], "namespace": "object.func" } - ] + ], + "events": [] }, "path": [ { @@ -824,7 +838,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -864,7 +879,8 @@ "kind": "member", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -911,7 +927,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -951,7 +968,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -991,7 +1009,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1035,7 +1054,8 @@ }, "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1079,7 +1099,8 @@ }, "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1123,7 +1144,8 @@ }, "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1174,7 +1196,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1213,7 +1236,8 @@ "name": "o1", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1252,7 +1276,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1354,7 +1379,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1393,7 +1419,8 @@ "name": "o2", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1432,7 +1459,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/es6-class.output.json b/test/fixture/es6-class.output.json index acdacf6b3..20a562615 100644 --- a/test/fixture/es6-class.output.json +++ b/test/fixture/es6-class.output.json @@ -86,7 +86,8 @@ "kind": "class", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -281,7 +282,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -388,7 +390,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/es6-default2.output.json b/test/fixture/es6-default2.output.json index 17bb6cac3..43a0cc58f 100644 --- a/test/fixture/es6-default2.output.json +++ b/test/fixture/es6-default2.output.json @@ -43,7 +43,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/es6-import.output.json b/test/fixture/es6-import.output.json index 8388f25d0..4c3b25624 100644 --- a/test/fixture/es6-import.output.json +++ b/test/fixture/es6-import.output.json @@ -157,7 +157,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -247,7 +248,8 @@ "name": "es6-ext", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -407,7 +409,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/es6.output.json b/test/fixture/es6.output.json index 4e899117d..62862566d 100644 --- a/test/fixture/es6.output.json +++ b/test/fixture/es6.output.json @@ -115,7 +115,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -244,7 +245,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -500,7 +502,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -674,7 +677,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -772,7 +776,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -874,7 +879,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1064,7 +1070,8 @@ "scope": "instance", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1164,7 +1171,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1341,7 +1349,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1590,7 +1599,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1691,7 +1701,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1796,7 +1807,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -1887,7 +1899,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -2048,7 +2061,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -2146,7 +2160,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -2244,7 +2259,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -2342,7 +2358,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -2432,7 +2449,8 @@ "name": "execute", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -2601,7 +2619,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/event.output.json b/test/fixture/event.output.json index 934cbf267..ae349584c 100644 --- a/test/fixture/event.output.json +++ b/test/fixture/event.output.json @@ -237,7 +237,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/example-caption.output.json b/test/fixture/example-caption.output.json index 1a9091b06..7fb36daf6 100644 --- a/test/fixture/example-caption.output.json +++ b/test/fixture/example-caption.output.json @@ -213,7 +213,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/external.output.json b/test/fixture/external.output.json index 929a6a4c4..c8e02a0b7 100644 --- a/test/fixture/external.output.json +++ b/test/fixture/external.output.json @@ -114,7 +114,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/factory.output.json b/test/fixture/factory.output.json index 4b9d07561..7e7078904 100644 --- a/test/fixture/factory.output.json +++ b/test/fixture/factory.output.json @@ -150,7 +150,8 @@ "kind": "function", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -205,7 +206,8 @@ ], "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { @@ -317,7 +319,8 @@ "scope": "static", "members": { "instance": [], - "static": [] + "static": [], + "events": [] }, "path": [ { diff --git a/test/fixture/html/nested.config-output.html b/test/fixture/html/nested.config-output.html index 4250860a2..626338271 100644 --- a/test/fixture/html/nested.config-output.html +++ b/test/fixture/html/nested.config-output.html @@ -76,12 +76,6 @@

.MAGIC_NUMBER -
  • - .event -
    • - @@ -103,6 +97,17 @@

    + + @@ -628,51 +633,6 @@

    - - - - - - - - - -
    -
    -
    - ▸ - event -
    -
    - @@ -590,51 +595,6 @@ k.isArrayOfBuffers(); - - - - - - -
    - - -
    -
    -
    - ▸ - event -
    -
    -