Skip to content

Commit

Permalink
tools: allow multiple added: version entries
Browse files Browse the repository at this point in the history
Allow multiple `added:` version entries, since semver-minors
can trickle down to previous major versions, and thus
features may have been added in multiple versions.

Also include `deprecated:` entries and apply the same logic
to them for consistency.

Stylize the added HTML as `Added in:` and `Deprecated since:`.

PR-URL: nodejs#6495
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
  • Loading branch information
addaleax committed Jul 12, 2016
1 parent de131cb commit cab73be
Show file tree
Hide file tree
Showing 5 changed files with 58 additions and 11 deletions.
9 changes: 7 additions & 2 deletions test/doctool/test-doctool-html.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,17 @@ const testData = [
' id="foo_sample_markdown_with_yaml_info">#</a></span></h1>' +
'<h2>Foobar<span><a class="mark" href="#foo_foobar" ' +
'id="foo_foobar">#</a></span></h2>' +
'<div class="api_metadata"><span>Added: v1.0.0</span></div> ' +
'<div class="api_metadata"><span>Added in: v1.0.0</span></div> ' +
'<p>Describe <code>Foobar</code> in more detail here.</p>' +
'<h2>Foobar II<span><a class="mark" href="#foo_foobar_ii" ' +
'id="foo_foobar_ii">#</a></span></h2>' +
'<div class="api_metadata"><span>Added in: v5.3.0, v4.2.0</span></div> ' +
'<p>Describe <code>Foobar II</code> in more detail here.</p>' +
'<h2>Deprecated thingy<span><a class="mark" ' +
'href="#foo_deprecated_thingy" id="foo_deprecated_thingy">#</a>' +
'</span></h2>' +
'<div class="api_metadata"><span>Added: v1.0.0</span></div><p>Describe ' +
'<div class="api_metadata"><span>Added in: v1.0.0</span>' +
'<span>Deprecated since: v2.0.0</span></div><p>Describe ' +
'<code>Deprecated thingy</code> in more detail here.</p>' +
'<h2>Something<span><a class="mark" href="#foo_something" ' +
'id="foo_something">#</a></span></h2> ' +
Expand Down
17 changes: 14 additions & 3 deletions test/doctool/test-doctool-json.js
Original file line number Diff line number Diff line change
Expand Up @@ -78,19 +78,30 @@ var testData = [
'textRaw': 'Foobar',
'name': 'foobar',
'meta': {
'added': 'v1.0.0'
'added': ['v1.0.0']
},
'desc': '<p>Describe <code>Foobar</code> in more detail ' +
'here.\n\n</p>\n',
'type': 'module',
'displayName': 'Foobar'
},
{
'textRaw': 'Foobar II',
'name': 'foobar_ii',
'meta': {
'added': ['v5.3.0', 'v4.2.0']
},
'desc': '<p>Describe <code>Foobar II</code> in more detail ' +
'here.\n\n</p>\n',
'type': 'module',
'displayName': 'Foobar II'
},
{
'textRaw': 'Deprecated thingy',
'name': 'deprecated_thingy',
'meta': {
'added': 'v1.0.0',
'deprecated': 'v2.0.0'
'added': ['v1.0.0'],
'deprecated': ['v2.0.0']
},
'desc': '<p>Describe <code>Deprecated thingy</code> in more ' +
'detail here.\n\n</p>\n',
Expand Down
9 changes: 9 additions & 0 deletions test/fixtures/doc_with_yaml.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@ added: v1.0.0

Describe `Foobar` in more detail here.

## Foobar II
<!-- YAML
added:
- v5.3.0
- v4.2.0
-->

Describe `Foobar II` in more detail here.

## Deprecated thingy
<!-- YAML
added: v1.0.0
Expand Down
21 changes: 20 additions & 1 deletion tools/doc/common.js
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,33 @@ function isYAMLBlock(text) {

exports.isYAMLBlock = isYAMLBlock;

function arrify(value) {
return Array.isArray(value) ? value : [value];
}

function extractAndParseYAML(text) {
text = text.trim();

text = text.replace(/^<!-- YAML/, '')
.replace(/-->$/, '');

// js-yaml.safeLoad() throws on error
return yaml.safeLoad(text);
const meta = yaml.safeLoad(text);

const added = meta.added || meta.Added;
if (added) {
// Since semver-minors can trickle down to previous major versions,
// features may have been added in multiple versions.
meta.added = arrify(added);
}

const deprecated = meta.deprecated || meta.Deprecated;
if (deprecated) {
// Treat deprecated like added for consistency.
meta.deprecated = arrify(deprecated);
}

return meta;
}

exports.extractAndParseYAML = extractAndParseYAML;
13 changes: 8 additions & 5 deletions tools/doc/html.js
Original file line number Diff line number Diff line change
Expand Up @@ -180,15 +180,18 @@ function parseLists(input) {

function parseYAML(text) {
const meta = common.extractAndParseYAML(text);
let html = '<div class="api_metadata">';
const html = ['<div class="api_metadata">'];

if (meta.added || meta.Added) {
meta.added = meta.added || meta.Added;
if (meta.added) {
html.push(`<span>Added in: ${meta.added.join(', ')}</span>`);
}

html += '<span>Added: ' + meta.added + '</span>';
if (meta.deprecated) {
html.push(`<span>Deprecated since: ${meta.deprecated.join(', ')} </span>`);
}

return html + '</div>';
html.push('</div>');
return html.join('\n');
}

// Syscalls which appear in the docs, but which only exist in BSD / OSX
Expand Down

0 comments on commit cab73be

Please sign in to comment.