pFad - Phonifier reborn

From 24ac6482f9ec35f018d09fa9cc34a2b3066f05fd Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Fri, 25 Nov 2016 18:14:52 -0500 Subject: [PATCH] Output typedef content in Markdown and HTML. Fixes #359 --- 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": [ 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

new Klass(foo: any) + + Extends @@ -321,6 +323,8 @@