archive-gh-me/documentation
1
0
Fork 0
mirror of https://github.com/documentationjs/documentation.git synced 2026-01-18 14:17:30 +00:00
Code Issues Projects Releases Wiki Activity

Restore default values. Fix sort test

Browse Source
This commit is contained in:
Tom MacWright 2016-05-05 10:00:57 -04:00
parent 888f5eccfb
commit bb41619c73
11 changed files with 316 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
lib/parse.js
View File

@ -154,6 +154,10 @@ var flatteners = {
param.type = tag.type;
}
if (tag.default) {
param.default = tag.default;
}
result.params.push(param);
},
'private': function (result) {

75
lib/sort.js
View File

@ -11,50 +11,49 @@ function parseMarkdown(string) {
* Sort two documentation objects, given an optional order object. Returns
* a numeric sorting value that is compatible with stream-sort.
*
* @param {Object} a documentation object
* @param {Object} b documentation object
* @param {Array<Object>} comments all comments
* @param {Object} options options from documentation.yml
* @return {number} sorting value
* @private
*/
module.exports = function sortDocs(comments, options) {
if (!options.toc) {
if (!options || !options.toc) {
return comments.sort(function (a, b) {
return a.context.sortKey.localeCompare(b.context.sortKey);
});
} else {
var indexes = options.toc.reduce(function (memo, val, i) {
if (typeof val === 'object' && val.name) {
val.kind = 'note';
memo[val.name] = i;
} else {
memo[val] = i;
}
return memo;
}, {});
var fixed = options.toc.filter(function (val) {
return typeof val === 'object' && val.name;
}).map(function (val) {
if (val.description) {
val.description = parseMarkdown(val.description);
}
return val;
});
var unfixed = [];
comments.forEach(function (comment) {
if (!comment.memberof && indexes[comment.name] !== undefined) {
fixed.push(comment);
} else {
unfixed.push(comment);
}
});
fixed.sort(function (a, b) {
if (indexes[a.name] !== undefined && indexes[b.name] !== undefined) {
return indexes[a.name] - indexes[b.name];
}
});
unfixed.sort(function (a, b) {
return a.context.sortKey.localeCompare(b.context.sortKey);
});
return fixed.concat(unfixed);
}
var indexes = options.toc.reduce(function (memo, val, i) {
if (typeof val === 'object' && val.name) {
val.kind = 'note';
memo[val.name] = i;
} else {
memo[val] = i;
}
return memo;
}, {});
var fixed = options.toc.filter(function (val) {
return typeof val === 'object' && val.name;
}).map(function (val) {
if (val.description) {
val.description = parseMarkdown(val.description);
}
return val;
});
var unfixed = [];
comments.forEach(function (comment) {
if (!comment.memberof && indexes[comment.name] !== undefined) {
fixed.push(comment);
} else {
unfixed.push(comment);
}
});
fixed.sort(function (a, b) {
if (indexes[a.name] !== undefined && indexes[b.name] !== undefined) {
return indexes[a.name] - indexes[b.name];
}
});
unfixed.sort(function (a, b) {
return a.context.sortKey.localeCompare(b.context.sortKey);
});
return fixed.concat(unfixed);
};

43
test/fixture/html/nested.output.files
View File

@ -26,10 +26,7 @@
<li><a
href='#Klass'
class='toggle-sibling'
>
class=" toggle-sibling">
Klass
<span class='icon'>▸</span>
</a>
@ -103,8 +100,7 @@
<li><a
href='#bar'
>
class="">
bar
</a>
@ -114,8 +110,7 @@
<li><a
href='#bar'
>
class="">
bar
</a>
@ -125,8 +120,7 @@
<li><a
href='#bar'
>
class="">
bar
</a>
@ -136,10 +130,7 @@
<li><a
href='#Foo'
class='toggle-sibling'
>
class=" toggle-sibling">
Foo
<span class='icon'>▸</span>
</a>
@ -170,7 +161,8 @@
<div class='fix-margin-3'>
<div class='px2'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h3 id='Klass' class='mt0'>
Klass
@ -401,7 +393,9 @@ the referenced class type</p>
</li>
<li><code>size</code> <em>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>])</em>: size
<li><code>size</code> <em>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>]
(default <code>0</code>)
)</em>: size
</li>
@ -758,8 +752,10 @@ k.isArrayOfBuffers();</pre>
</div>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h3 id='bar' class='mt0'>
bar
@ -806,8 +802,10 @@ like a <a href="#Klass">klass</a></p>
</div>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h3 id='bar' class='mt0'>
bar
@ -861,8 +859,10 @@ like a <a href="#Klass">klass</a></p>
</div>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h3 id='bar' class='mt0'>
bar
@ -909,8 +909,10 @@ like a <a href="#Klass">klass</a>. This needs a <a href="#number">number</a> inp
</div>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h3 id='Foo' class='mt0'>
Foo
@ -1003,6 +1005,7 @@ like a <a href="#Klass">klass</a>. This needs a <a href="#number">number</a> inp
</div>
</div>
</div>

3
test/fixture/nest_params.input.js
View File

@ -2,8 +2,9 @@
* @param {Object[]} employees - The employees who are responsible for the project.
* @param {string} employees[].name - The name of an employee.
* @param {string} employees[].department - The employee's department.
* @param {string} [type=minion] - The employee's type.
*/
function foo(employee) {
function foo(employee, type) {
}
/**

96
test/fixture/nest_params.output.json
View File

@ -40,6 +40,20 @@
"name": "string"
},
"name": "employees[].department"
},
{
"title": "param",
"description": "The employee's type.",
"lineNumber": 4,
"type": {
"type": "OptionalType",
"expression": {
"type": "NameExpression",
"name": "string"
}
},
"name": "type",
"default": "minion"
}
],
"loc": {
@ -48,22 +62,22 @@
"column": 0
},
"end": {
"line": 5,
"line": 6,
"column": 3
}
},
"context": {
"loc": {
"start": {
"line": 6,
"line": 7,
"column": 0
},
"end": {
"line": 7,
"line": 8,
"column": 1
}
},
"code": "/**\n * @param {Object[]} employees - The employees who are responsible for the project.\n * @param {string} employees[].name - The name of an employee.\n * @param {string} employees[].department - The employee's department.\n */\nfunction foo(employee) {\n}\n\n/**\n * @name foo\n * @param {Object} options some options\n * @param {number} options.much how much\n * @param {number} bar something else\n * @property {Object} theTime the current time\n * @property {number} theTime.hours\n * @property {number} theTime.minutes\n * @property {number} theTime.seconds\n * @returns {Object} foo something else\n */\n"
"code": "/**\n * @param {Object[]} employees - The employees who are responsible for the project.\n * @param {string} employees[].name - The name of an employee.\n * @param {string} employees[].department - The employee's department.\n * @param {string} [type=minion] - The employee's type.\n */\nfunction foo(employee, type) {\n}\n\n/**\n * @name foo\n * @param {Object} options some options\n * @param {number} options.much how much\n * @param {number} bar something else\n * @property {Object} theTime the current time\n * @property {number} theTime.hours\n * @property {number} theTime.minutes\n * @property {number} theTime.seconds\n * @returns {Object} foo something else\n */\n"
},
"errors": [],
"params": [
@ -261,7 +275,71 @@
{
"title": "param",
"name": "employee",
"lineNumber": 6
"lineNumber": 7
},
{
"name": "type",
"lineNumber": 4,
"description": {
"type": "root",
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The employee's type.",
"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
}
}
},
"type": {
"type": "OptionalType",
"expression": {
"type": "NameExpression",
"name": "string"
}
},
"default": "minion"
}
],
"name": "foo",
@ -369,22 +447,22 @@
],
"loc": {
"start": {
"line": 9,
"line": 10,
"column": 0
},
"end": {
"line": 19,
"line": 20,
"column": 3
}
},
"context": {
"loc": {
"start": {
"line": 6,
"line": 7,
"column": 0
},
"end": {
"line": 7,
"line": 8,
"column": 1
}
}

1
test/fixture/nest_params.output.md
View File

@ -6,6 +6,7 @@
- `employees[].name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of an employee.
- `employees[].department` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The employee's department.
- `employee`
- `type` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** The employee's type. (optional, default `minion`)
# foo

98
test/fixture/nest_params.output.md.json
View File

@ -289,6 +289,104 @@
]
}
]
},
{
"type": "listItem",
"children": [
{
"type": "paragraph",
"children": [
{
"type": "inlineCode",
"value": "type"
},
{
"type": "text",
"value": " "
},
{
"type": "strong",
"children": [
{
"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": "]"
}
]
},
{
"type": "text",
"value": " "
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The employee's type.",
"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": " (optional, default "
},
{
"type": "inlineCode",
"value": "minion"
},
{
"type": "text",
"value": ")"
}
]
}
]
}
]
}
]
},

9
test/fixture/params.output.json
View File

@ -1064,7 +1064,8 @@
"type": "NameExpression",
"name": "number"
}
}
},
"default": "8"
},
{
"name": "third",
@ -1191,7 +1192,8 @@
"type": "NameExpression",
"name": "Array"
}
}
},
"default": "[1]"
}
],
"examples": [
@ -1604,7 +1606,8 @@
"type": "NameExpression",
"name": "number"
}
}
},
"default": "14"
},
{
"name": "options.buffer",

6
test/fixture/params.output.md
View File

@ -51,9 +51,9 @@ This tests our support of optional parameters
**Parameters**
- `address` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** An IPv6 address string
- `groups` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** How many octets to parse
- `groups` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** How many octets to parse (optional, default `8`)
- `third` **?[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** A third argument
- `foo` **\[[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)]** to properly be parsed
- `foo` **\[[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)]** to properly be parsed (optional, default `[1]`)
**Examples**
@ -72,7 +72,7 @@ This tests our support of nested parameters
- `options` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** optional options
- `options.data` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** A GeoJSON data object or URL to it.
The latter is preferable in case of large GeoJSON files.
- `options.maxzoom` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Maximum zoom to preserve detail at.
- `options.maxzoom` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Maximum zoom to preserve detail at. (optional, default `14`)
- `options.buffer` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Tile buffer on each side.
- `options.tolerance` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Simplification tolerance (higher means simpler).

51
test/fixture/params.output.md.json
View File

@ -1017,6 +1017,23 @@
},
"indent": []
}
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": " (optional, default "
},
{
"type": "inlineCode",
"value": "8"
},
{
"type": "text",
"value": ")"
}
]
}
]
}
@ -1175,6 +1192,23 @@
},
"indent": []
}
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": " (optional, default "
},
{
"type": "inlineCode",
"value": "[1]"
},
{
"type": "text",
"value": ")"
}
]
}
]
}
@ -1548,6 +1582,23 @@
},
"indent": []
}
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": " (optional, default "
},
{
"type": "inlineCode",
"value": "14"
},
{
"type": "text",
"value": ")"
}
]
}
]
}

8
test/lib/sort.js
View File

@ -8,15 +8,15 @@ test('sort stream alphanumeric', function (t) {
var carrot = { context: { sortKey: 'b' }, name: 'carrot' };
var banana = { context: { sortKey: 'c' }, name: 'bananas' };
t.deepEqual([
t.deepEqual(sort([
apples, carrot, banana
].sort(sort), [
]), [
apples, carrot, banana
], 'sort stream alphanumeric');
t.deepEqual([
t.deepEqual(sort([
carrot, apples, banana
].sort(sort), [
]), [
apples, carrot, banana
], 'sort stream alphanumeric');