Skip to content

Commit 2ac4d04

Browse files
tmcwtmcw
authored
Format optional types with ? instead of [] (#538)
* Format optional types with ? instead of [] Fixes #509 * ? as postfix not prefix * Update test fixtures
1 parent 1c48a4f commit 2ac4d04

18 files changed

+114
-179
lines changed

‎default_theme/section._

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@
4343
<div class='space-bottom0'>
4444
<div>
4545
<span class='code bold'><%- param.name%></span> <code class='quiet'>(<%= formatType(param.type) %><% if (param.default) { %>
46-
(default <code><%- param.default %></code>)
47-
<% } %>)</code> <%= md(param.description, true) %>
46+
= <code><%- param.default %></code><% } %>)</code>
47+
<%= md(param.description, true) %>
4848
</div>
4949
<% if (param.properties) { %>
5050
<table class='mt1 mb2 fixed-table h5 col-12'>

‎lib/output/util/format_type.js

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ function commaList(getHref, items, start, end, sep) {
7373
*
7474
* @param {Array<Object>} formatted remark AST of a type definition
7575
* @param {string} str postfix
76-
* @param {string} prefix string to put after the type comment
76+
* @param {boolean} prefix string to put after the type comment
7777
* @returns {Array<Object>} suffixed and potentially prefixed type
7878
*/
7979
function decorate(formatted, str, prefix) {
@@ -163,12 +163,15 @@ function formatType(getHref, node) {
163163
// lets the expression be omitted.
164164
return decorate(formatType(getHref, node.expression), '...', true);
165165
case Syntax.OptionalType:
166-
return decorate(decorate(formatType(getHref, node.expression), '[', true), ']').concat(
167-
node.default ? t('(default ' + node.default + ')') : []);
166+
if (node.default) {
167+
return decorate(formatType(getHref, node.expression), '?')
168+
.concat(t('= ' + node.default));
169+
}
170+
return decorate(formatType(getHref, node.expression), '?');
168171
case Syntax.NonNullableType:
169172
return decorate(formatType(getHref, node.expression), '!', node.prefix);
170173
case Syntax.NullableType:
171-
return decorate(formatType(getHref, node.expression), '?', node.prefix);
174+
return decorate(formatType(getHref, node.expression), '?');
172175
case Syntax.StringLiteralType:
173176
return [u('inlineCode', JSON.stringify(node.value))];
174177
case Syntax.NumericLiteralType:

‎lib/output/util/formatters.js

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,13 @@ module.exports = function (getHref) {
2828
*/
2929
formatters.parameter = function (param, short) {
3030
if (short) {
31-
return (param.type && param.type.type == Syntax.OptionalType) ?
32-
'[' + param.name + ']' : param.name;
31+
if (param.type && param.type.type == Syntax.OptionalType) {
32+
if (param.default) {
33+
return param.name + ' = ' + param.default;
34+
}
35+
return param.name + '?';
36+
}
37+
return param.name;
3338
}
3439
return param.name + ': ' + formatters.type(param.type).replace(/\n/g, '');
3540
};

‎test/fixture/html/nested.output.files

Lines changed: 24 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,8 @@
240240

241241
<div class='space-bottom0'>
242242
<div>
243-
<span class='code bold'>foo</span> <code class='quiet'>(any)</code>
243+
<span class='code bold'>foo</span> <code class='quiet'>(any)</code>
244+
244245
</div>
245246

246247
</div>
@@ -293,14 +294,16 @@ This is a [link to something that does not exist]<a href="DoesNot">DoesNot</a></
293294

294295
<div class='space-bottom0'>
295296
<div>
296-
<span class='code bold'>other</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
297+
<span class='code bold'>other</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
298+
297299
</div>
298300

299301
</div>
300302

301303
<div class='space-bottom0'>
302304
<div>
303-
<span class='code bold'>also</span> <code class='quiet'>(any)</code>
305+
<span class='code bold'>also</span> <code class='quiet'>(any)</code>
306+
304307
</div>
305308

306309
</div>
@@ -366,7 +369,8 @@ the referenced class type</p>
366369

367370
<div class='space-bottom0'>
368371
<div>
369-
<span class='code bold'>other</span> <code class='quiet'>(Weird)</code>
372+
<span class='code bold'>other</span> <code class='quiet'>(Weird)</code>
373+
370374
</div>
371375

372376
</div>
@@ -404,7 +408,7 @@ the referenced class type</p>
404408
<div class="clearfix small pointer toggle-sibling">
405409
<div class="py1 contain">
406410
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
407-
<span class='code strong strong truncate'>isBuffer(buf, [size])</span>
411+
<span class='code strong strong truncate'>isBuffer(buf, size = 0)</span>
408412
</div>
409413
</div>
410414
<div class="clearfix display-none toggle-target">
@@ -415,7 +419,7 @@ the referenced class type</p>
415419
<p>This method takes a Buffer object that will be linked to nodejs.org</p>
416420

417421

418-
<div class='pre p1 fill-light mt0'>isBuffer(buf: (<a href="https://nodejs.org/api/buffer.html">Buffer</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>), size: [<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>]): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></div>
422+
<div class='pre p1 fill-light mt0'>isBuffer(buf: (<a href="https://nodejs.org/api/buffer.html">Buffer</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>), size: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>?): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></div>
419423

420424

421425

@@ -431,16 +435,17 @@ the referenced class type</p>
431435

432436
<div class='space-bottom0'>
433437
<div>
434-
<span class='code bold'>buf</span> <code class='quiet'>((<a href="https://nodejs.org/api/buffer.html">Buffer</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>))</code>
438+
<span class='code bold'>buf</span> <code class='quiet'>((<a href="https://nodejs.org/api/buffer.html">Buffer</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>))</code>
439+
435440
</div>
436441

437442
</div>
438443

439444
<div class='space-bottom0'>
440445
<div>
441-
<span class='code bold'>size</span> <code class='quiet'>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>]
442-
(default <code>0</code>)
443-
)</code> size
446+
<span class='code bold'>size</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>?
447+
= <code>0</code>)</code>
448+
size
444449

445450
</div>
446451

@@ -506,7 +511,8 @@ the referenced class type</p>
506511

507512
<div class='space-bottom0'>
508513
<div>
509-
<span class='code bold'>buffers</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://nodejs.org/api/buffer.html">Buffer</a>>)</code> some buffers
514+
<span class='code bold'>buffers</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="https://nodejs.org/api/buffer.html">Buffer</a>>)</code>
515+
some buffers
510516

511517
</div>
512518

@@ -721,7 +727,7 @@ k.isArrayOfBuffers();</pre>
721727
<p>A function with an options parameter</p>
722728

723729

724-
<div class='pre p1 fill-light mt0'>withOptions(options: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, otherOptions: ?<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</div>
730+
<div class='pre p1 fill-light mt0'>withOptions(options: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, otherOptions: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>?)</div>
725731

726732

727733

@@ -737,7 +743,8 @@ k.isArrayOfBuffers();</pre>
737743

738744
<div class='space-bottom0'>
739745
<div>
740-
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
746+
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
747+
741748
</div>
742749

743750
<table class='mt1 mb2 fixed-table h5 col-12'>
@@ -772,7 +779,8 @@ k.isArrayOfBuffers();</pre>
772779

773780
<div class='space-bottom0'>
774781
<div>
775-
<span class='code bold'>otherOptions</span> <code class='quiet'>(?<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code>
782+
<span class='code bold'>otherOptions</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>?)</code>
783+
776784
</div>
777785

778786
</div>
@@ -968,7 +976,8 @@ like a <a href="#klass">klass</a></p>
968976

969977
<div class='space-bottom0'>
970978
<div>
971-
<span class='code bold'>toys</span> <code class='quiet'>(...<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>)</code>
979+
<span class='code bold'>toys</span> <code class='quiet'>(...<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>)</code>
980+
972981
</div>
973982

974983
</div>

‎test/fixture/nearby_params.output.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,6 @@ Attempt to establish a cookie-based session in exchange for credentials.
99
- `credentials` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
1010
- `credentials.name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Login username. Also accepted as `username` or `email`.
1111
- `credentials.password` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Login password
12-
- `callback` **\[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Gets passed `(err, { success:Boolean })`.
12+
- `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Gets passed `(err, { success:Boolean })`.
1313

1414
Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** promise, to be resolved on success or rejected on failure

‎test/fixture/nearby_params.output.md.json

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -338,10 +338,6 @@
338338
{
339339
"type": "strong",
340340
"children": [
341-
{
342-
"type": "text",
343-
"value": "["
344-
},
345341
{
346342
"href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function",
347343
"url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function",
@@ -355,7 +351,7 @@
355351
},
356352
{
357353
"type": "text",
358-
"value": "]"
354+
"value": "?"
359355
}
360356
]
361357
},

‎test/fixture/nest_params.output.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
- `employees` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** The employees who are responsible for the project.
88
- `employees[].name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of an employee.
99
- `employees[].department` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The employee's department.
10-
- `type` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** The employee's type. (optional, default `minion`)
10+
- `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The employee's type. (optional, default `minion`)
1111

1212
# foo
1313

‎test/fixture/nest_params.output.md.json

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -289,10 +289,6 @@
289289
{
290290
"type": "strong",
291291
"children": [
292-
{
293-
"type": "text",
294-
"value": "["
295-
},
296292
{
297293
"href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String",
298294
"url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String",
@@ -306,7 +302,7 @@
306302
},
307303
{
308304
"type": "text",
309-
"value": "]"
305+
"value": "?"
310306
}
311307
]
312308
},

‎test/fixture/optional-record-field-type.output.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@
44

55
**Properties**
66

7-
- `opt` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]**
7+
- `opt` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?**
88
- `req` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**

‎test/fixture/optional-record-field-type.output.md.json

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,6 @@
4545
{
4646
"type": "strong",
4747
"children": [
48-
{
49-
"type": "text",
50-
"value": "["
51-
},
5248
{
5349
"href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number",
5450
"url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number",
@@ -62,7 +58,7 @@
6258
},
6359
{
6460
"type": "text",
65-
"value": "]"
61+
"value": "?"
6662
}
6763
]
6864
},

0 commit comments

Comments
 (0)