From cd65dc39cfa7051dc42005d3ff32596ccf7cb355 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Sun, 29 Jan 2017 19:10:04 -0500 Subject: [PATCH] Support deprecated tag (#666) --- default_theme/section._ | 15 +- lib/output/markdown_ast.js | 4 +- lib/parse.js | 6 +- test/fixture/html/nested.config-output.html | 418 ++------------------ test/fixture/html/nested.output.files | 418 ++------------------ 5 files changed, 65 insertions(+), 796 deletions(-) diff --git a/default_theme/section._ b/default_theme/section._ index a75159b..4ef057f 100644 --- a/default_theme/section._ +++ b/default_theme/section._ @@ -24,7 +24,7 @@ <%= formatType(section.type) %>

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

Extends <% if (section.augments) { %> @@ -35,13 +35,14 @@

<% } %> + <% if (section.deprecated) { %>
Deprecated: <%= md(section.deprecated, true) %>
<% }%> <% if (section.version) { %>
Version: <%- section.version %>
<% }%> <% if (section.license) { %>
License: <%- section.license %>
<% }%> <% if (section.author) { %>
Author: <%- section.author %>
<% }%> - <% if (section.copyright) { %>
Copyright: <%- section.copyright %>
<% }%> + <% if (section.copyright) { %>
Copyright: <%= md(section.copyright, true) %>
<% }%> <% if (section.since) { %>
Since: <%- section.since %>
<% }%> - <% if (section.params) { %> + <% if (section.params.length) { %>
Parameters
<% section.params.forEach(function(param) { %> @@ -81,7 +82,7 @@
<% } %> - <% if (section.properties) { %> + <% if (section.properties.length) { %>
Properties
<% section.properties.forEach(function(property) { %> @@ -108,7 +109,7 @@
<% } %> - <% if (section.returns) { %> + <% if (section.returns.length) { %> <% section.returns.forEach(function(ret) { %>
Returns
<%= formatType(ret.type) %><% if (ret.description) { %>: @@ -117,7 +118,7 @@ <% }) %> <% } %> - <% if (section.throws) { %> + <% if (section.throws.length) { %>
Throws
<% } %> - <% if (section.examples) { %> + <% if (section.examples.length) { %>
Example
<% section.examples.forEach(function(example) { %> <% if (example.caption) { %>

<%= md(example.caption) %>

<% } %> diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js index 8c9748f..4058603 100644 --- a/lib/output/markdown_ast.js +++ b/lib/output/markdown_ast.js @@ -174,14 +174,14 @@ function buildMarkdownAST(comments/*: Array */, config/*: Documentation } function metaSection(comment/*: Comment */) { - let meta = ['version', 'since', 'copyright', 'author', 'license'] + let meta = ['version', 'since', 'copyright', 'author', 'license', 'deprecated'] .filter(tag => comment[tag]); return !!meta.length && [u('strong', [u('text', 'Meta')])].concat( u('list', { ordered: false }, meta .map(tag => { let metaContent; - if (tag === 'copyright') { + if (tag === 'copyright' || tag === 'deprecated') { metaContent = comment[tag]; } else { metaContent = u('text', comment[tag]); diff --git a/lib/parse.js b/lib/parse.js index 176f990..1b859a5 100644 --- a/lib/parse.js +++ b/lib/parse.js @@ -77,7 +77,11 @@ var flatteners = { 'copyright': flattenMarkdownDescription, 'default': todo, 'defaultvalue': synonym('default'), - 'deprecated': flattenMarkdownDescription, + deprecated(result, tag) { + let description = tag.description || 'This is deprecated.'; + result.deprecated = parseMarkdown(description); + }, + flattenMarkdownDescription, 'desc': synonym('description'), 'description': flattenMarkdownDescription, 'emits': synonym('fires'), diff --git a/test/fixture/html/nested.config-output.html b/test/fixture/html/nested.config-output.html index 534109b..0367dc1 100644 --- a/test/fixture/html/nested.config-output.html +++ b/test/fixture/html/nested.config-output.html @@ -279,6 +279,7 @@ PeerId.create({ bits: 1 +
Parameters
@@ -296,27 +297,12 @@ PeerId.create({ bits: 1 -
Properties
-
- -
+ - - -
Throws
-
    - -
- - - -
Example
- -
Static Members
@@ -342,19 +328,13 @@ This is a [link to something that does not exist]DoesNotisClass(other: Object, also: any): boolean -

- Extends - - - -

- +
Parameters
@@ -380,11 +360,6 @@ This is a [link to something that does not exist]DoesNotProperties -
- -
- @@ -397,16 +372,8 @@ This is a [link to something that does not exist]DoesNotThrows -
    - -
- -
Example
- - @@ -437,19 +404,13 @@ the referenced class type

isWeird(other: Weird): boolean
-

- Extends - - - -

- +
Parameters
@@ -467,11 +428,6 @@ the referenced class type

-
Properties
-
- -
- @@ -484,16 +440,8 @@ the referenced class type

-
Throws
-
    - -
- -
Example
- - @@ -523,19 +471,13 @@ the referenced class type

isBuffer(buf: (Buffer | string), size: number?): boolean
-

- Extends - - - -

- +
Parameters
@@ -563,11 +505,6 @@ the referenced class type

-
Properties
-
- -
- @@ -580,16 +517,8 @@ the referenced class type

-
Throws
-
    - -
- -
Example
- - @@ -619,19 +548,13 @@ the referenced class type

isArrayOfBuffers(buffers: Array<Buffer>): number
-

- Extends - - - -

- +
Parameters
@@ -650,11 +573,6 @@ the referenced class type

-
Properties
-
- -
- @@ -667,11 +585,6 @@ the referenced class type

-
Throws
-
    - -
-
Example
@@ -710,49 +623,23 @@ k.isArrayOfBuffers();
MAGIC_NUMBER
-

- Extends - - - -

- + -
Parameters
-
- -
+ -
Properties
-
- -
- - - -
Throws
-
    - -
- - - -
Example
- - @@ -790,33 +677,17 @@ k.isArrayOfBuffers();
getFoo(): Number
-

- Extends - - - -

- + -
Parameters
-
- -
- -
Properties
-
- -
- @@ -829,11 +700,6 @@ k.isArrayOfBuffers(); -
Throws
-
    - -
-
Example
@@ -872,19 +738,13 @@ k.isArrayOfBuffers();
withOptions(options: Object, otherOptions: number?)
-

- Extends - - - -

- +
Parameters
@@ -938,27 +798,12 @@ k.isArrayOfBuffers(); -
Properties
-
- -
+ - - -
Throws
-
    - -
- - - -
Example
- - @@ -996,49 +841,23 @@ k.isArrayOfBuffers();
event
-

- Extends - - - -

- + -
Parameters
-
- -
+ -
Properties
-
- -
- - - -
Throws
-
    - -
- - - -
Example
- - @@ -1077,19 +896,13 @@ k.isArrayOfBuffers();
CustomError(other: any, also: any)
-

- Extends - - - -

- +
Parameters
@@ -1143,20 +956,10 @@ k.isArrayOfBuffers(); - - -
Throws
-
    - -
- -
Example
- - @@ -1189,33 +992,17 @@ like a klass

bar(): Klass
-

- Extends - - - -

- + -
Parameters
-
- -
- -
Properties
-
- -
- @@ -1228,16 +1015,8 @@ like a klass

-
Throws
-
    - -
- -
Example
- - @@ -1268,19 +1047,13 @@ like a klass

bar(toys: ...Number): undefined
-

- Extends - - - -

- +
Parameters
@@ -1298,11 +1071,6 @@ like a klass

-
Properties
-
- -
- @@ -1315,16 +1083,8 @@ like a klass

-
Throws
-
    - -
- -
Example
- - @@ -1357,33 +1117,17 @@ like a klass. This needs a undefined -

- Extends - - - -

- + -
Parameters
-
- -
- -
Properties
-
- -
- @@ -1396,16 +1140,8 @@ like a klass. This needs a klass. This needs a klass. This needs a klass. This needs a klass. This needs a DoesNotisClass(other: Object, also: any): boolean -

- Extends - - - -

- +
Parameters
@@ -342,11 +322,6 @@ This is a [link to something that does not exist]DoesNotProperties -
- -
- @@ -359,16 +334,8 @@ This is a [link to something that does not exist]DoesNotThrows -
    - -
- -
Example
- - @@ -399,19 +366,13 @@ the referenced class type

isWeird(other: Weird): boolean
-

- Extends - - - -

- +
Parameters
@@ -429,11 +390,6 @@ the referenced class type

-
Properties
-
- -
- @@ -446,16 +402,8 @@ the referenced class type

-
Throws
-
    - -
- -
Example
- - @@ -485,19 +433,13 @@ the referenced class type

isBuffer(buf: (Buffer | string), size: number?): boolean
-

- Extends - - - -

- +
Parameters
@@ -525,11 +467,6 @@ the referenced class type

-
Properties
-
- -
- @@ -542,16 +479,8 @@ the referenced class type

-
Throws
-
    - -
- -
Example
- - @@ -581,19 +510,13 @@ the referenced class type

isArrayOfBuffers(buffers: Array<Buffer>): number
-

- Extends - - - -

- +
Parameters
@@ -612,11 +535,6 @@ the referenced class type

-
Properties
-
- -
- @@ -629,11 +547,6 @@ the referenced class type

-
Throws
-
    - -
-
Example
@@ -672,49 +585,23 @@ k.isArrayOfBuffers();
MAGIC_NUMBER
-

- Extends - - - -

- + -
Parameters
-
- -
+ -
Properties
-
- -
- - - -
Throws
-
    - -
- - - -
Example
- - @@ -752,33 +639,17 @@ k.isArrayOfBuffers();
getFoo(): Number
-

- Extends - - - -

- + -
Parameters
-
- -
- -
Properties
-
- -
- @@ -791,11 +662,6 @@ k.isArrayOfBuffers(); -
Throws
-
    - -
-
Example
@@ -834,19 +700,13 @@ k.isArrayOfBuffers();
withOptions(options: Object, otherOptions: number?)
-

- Extends - - - -

- +
Parameters
@@ -900,27 +760,12 @@ k.isArrayOfBuffers(); -
Properties
-
- -
+ - - -
Throws
-
    - -
- - - -
Example
- - @@ -958,49 +803,23 @@ k.isArrayOfBuffers();
event
-

- Extends - - - -

- + -
Parameters
-
- -
+ -
Properties
-
- -
- - - -
Throws
-
    - -
- - - -
Example
- - @@ -1039,19 +858,13 @@ k.isArrayOfBuffers();
CustomError(other: any, also: any)
-

- Extends - - - -

- +
Parameters
@@ -1105,20 +918,10 @@ k.isArrayOfBuffers(); - - -
Throws
-
    - -
- -
Example
- - @@ -1151,33 +954,17 @@ like a klass

bar(): Klass
-

- Extends - - - -

- + -
Parameters
-
- -
- -
Properties
-
- -
- @@ -1190,16 +977,8 @@ like a klass

-
Throws
-
    - -
- -
Example
- - @@ -1230,19 +1009,13 @@ like a klass

bar(toys: ...Number): undefined
-

- Extends - - - -

- +
Parameters
@@ -1260,11 +1033,6 @@ like a klass

-
Properties
-
- -
- @@ -1277,16 +1045,8 @@ like a klass

-
Throws
-
    - -
- -
Example
- - @@ -1319,33 +1079,17 @@ like a klass. This needs a undefined -

- Extends - - - -

- + -
Parameters
-
- -
- -
Properties
-
- -
- @@ -1358,16 +1102,8 @@ like a klass. This needs a klass. This needs a klass. This needs a klass. This needs a klass. This needs a