Skip to content

Commit dcb318f

Browse files
ST-DDTST-DDT
authored
docs: fix unwrap literal union (#1752)
1 parent b86638d commit dcb318f

File tree

3 files changed

+92
-9
lines changed

3 files changed

+92
-9
lines changed

‎scripts/apidoc/signature.ts

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -277,20 +277,29 @@ function typeToText(type_?: Type, short = false): string {
277277

278278
const type = type_ as SomeType;
279279
switch (type.type) {
280-
case 'array':
281-
return `${typeToText(type.elementType, short)}[]`;
280+
case 'array': {
281+
const text = typeToText(type.elementType, short);
282+
if (text.includes('|') || text.includes('{')) {
283+
return `Array<${text}>`;
284+
} else {
285+
return `${text}[]`;
286+
}
287+
}
288+
282289
case 'union':
283290
return type.types
284291
.map((t) => typeToText(t, short))
292+
.map((t) => (t.includes('=>') ? `(${t})` : t))
285293
.sort()
286294
.join(' | ');
295+
287296
case 'reference':
288297
if (!type.typeArguments || !type.typeArguments.length) {
289298
return type.name;
290299
} else if (type.name === 'LiteralUnion') {
291300
return [
292-
typeToText(type.typeArguments[0]),
293-
typeToText(type.typeArguments[1]),
301+
typeToText(type.typeArguments[0], short),
302+
typeToText(type.typeArguments[1], short),
294303
].join(' | ');
295304
} else {
296305
return `${type.name}<${type.typeArguments
@@ -300,13 +309,25 @@ function typeToText(type_?: Type, short = false): string {
300309

301310
case 'reflection':
302311
return declarationTypeToText(type.declaration, short);
312+
303313
case 'indexedAccess':
304314
return `${typeToText(type.objectType, short)}[${typeToText(
305315
type.indexType,
306316
short
307317
)}]`;
318+
308319
case 'literal':
309320
return formatTypescript(type.toString()).replace(/;\n$/, '');
321+
322+
case 'typeOperator': {
323+
const text = typeToText(type.target, short);
324+
if (short && type.operator === 'readonly') {
325+
return text;
326+
} else {
327+
return `${type.operator} ${text}`;
328+
}
329+
}
330+
310331
default:
311332
return type.toString();
312333
}

‎test/scripts/apidoc/__snapshots__/signature.spec.ts.snap

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,10 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
55
"deprecated": false,
66
"description": "<p>Complex array parameter.</p>
77
",
8-
"examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">complexArrayParameter</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#FFCB6B\\">T</span><span style=\\"color:#89DDFF\\">&gt;</span><span style=\\"color:#A6ACCD\\">(array: readonly Object[]): T</span></span>
8+
"examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">complexArrayParameter</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#FFCB6B\\">T</span><span style=\\"color:#89DDFF\\">&gt;</span><span style=\\"color:#A6ACCD\\">(array: readonly </span><span style=\\"color:#82AAFF\\">Array</span><span style=\\"color:#89DDFF\\">&lt;{</span></span>
9+
<span class=\\"line\\"><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F07178\\">value</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#FFCB6B\\">T</span><span style=\\"color:#89DDFF\\">,</span></span>
10+
<span class=\\"line\\"><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#F07178\\">weight</span><span style=\\"color:#89DDFF\\">:</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#FFCB6B\\">number</span></span>
11+
<span class=\\"line\\"><span style=\\"color:#89DDFF\\">}&gt;</span><span style=\\"color:#A6ACCD\\">): T</span></span>
912
<span class=\\"line\\"></span></code></pre>
1013
</div>",
1114
"name": "complexArrayParameter",
@@ -21,7 +24,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
2124
"description": "<p>Array to pick the value from.</p>
2225
",
2326
"name": "array",
24-
"type": "readonly Object[]",
27+
"type": "Array<{ ... }>",
2528
},
2629
{
2730
"default": undefined,
@@ -123,7 +126,7 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
123126
"deprecated": false,
124127
"description": "<p>Test with LiteralUnion.</p>
125128
",
126-
"examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">literalUnionParamMethod</span><span style=\\"color:#A6ACCD\\">(value: </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string): string</span></span>
129+
"examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#A6ACCD\\">faker</span><span style=\\"color:#89DDFF\\">.</span><span style=\\"color:#82AAFF\\">literalUnionParamMethod</span><span style=\\"color:#A6ACCD\\">(value: </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">,</span><span style=\\"color:#A6ACCD\\"> namedValue: AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">,</span><span style=\\"color:#A6ACCD\\"> array: readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;,</span><span style=\\"color:#A6ACCD\\"> namedArray: readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#A6ACCD\\">AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;,</span><span style=\\"color:#A6ACCD\\"> mixed: </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">a</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#C3E88D\\">b</span><span style=\\"color:#89DDFF\\">'</span><span style=\\"color:#A6ACCD\\"> </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;,</span><span style=\\"color:#A6ACCD\\"> namedMixed: AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> readonly Array</span><span style=\\"color:#89DDFF\\">&lt;</span><span style=\\"color:#A6ACCD\\">AB </span><span style=\\"color:#89DDFF\\">|</span><span style=\\"color:#A6ACCD\\"> string</span><span style=\\"color:#89DDFF\\">&gt;</span><span style=\\"color:#A6ACCD\\">): string</span></span>
127130
<span class=\\"line\\"></span></code></pre>
128131
</div>",
129132
"name": "literalUnionParamMethod",
@@ -135,6 +138,41 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
135138
"name": "value",
136139
"type": "'a' | 'b' | string",
137140
},
141+
{
142+
"default": undefined,
143+
"description": "<p><code>'a'</code> or <code>'b'</code>.</p>
144+
",
145+
"name": "namedValue",
146+
"type": "AB | string",
147+
},
148+
{
149+
"default": undefined,
150+
"description": "<p>Array of <code>'a'</code> or <code>'b'</code>.</p>
151+
",
152+
"name": "array",
153+
"type": "Array<'a' | 'b' | string>",
154+
},
155+
{
156+
"default": undefined,
157+
"description": "<p>Array of <code>'a'</code> or <code>'b'</code>.</p>
158+
",
159+
"name": "namedArray",
160+
"type": "Array<AB | string>",
161+
},
162+
{
163+
"default": undefined,
164+
"description": "<p>Value <code>'a'</code> or <code>'b'</code> or an array thereof.</p>
165+
",
166+
"name": "mixed",
167+
"type": "'a' | 'b' | string | Array<'a' | 'b' | string>",
168+
},
169+
{
170+
"default": undefined,
171+
"description": "<p>Value <code>'a'</code> or <code>'b'</code> or an array thereof.</p>
172+
",
173+
"name": "namedMixed",
174+
"type": "AB | string | Array<AB | string>",
175+
},
138176
],
139177
"returns": "string",
140178
"seeAlsos": [],

‎test/scripts/apidoc/signature.example.ts

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,11 @@ export interface ParameterOptionsInterfaceC {
6060
value?: number;
6161
}
6262

63+
/**
64+
* A or B.
65+
*/
66+
export type AB = 'a' | 'b';
67+
6368
export class SignatureTest {
6469
/**
6570
* Test with no parameters.
@@ -128,9 +133,28 @@ export class SignatureTest {
128133
* Test with LiteralUnion.
129134
*
130135
* @param value `'a'` or `'b'`.
136+
* @param namedValue `'a'` or `'b'`.
137+
* @param array Array of `'a'` or `'b'`.
138+
* @param namedArray Array of `'a'` or `'b'`.
139+
* @param mixed Value `'a'` or `'b'` or an array thereof.
140+
* @param namedMixed Value `'a'` or `'b'` or an array thereof.
131141
*/
132-
literalUnionParamMethod(value: LiteralUnion<'a' | 'b'>): string {
133-
return value;
142+
literalUnionParamMethod(
143+
value: LiteralUnion<'a' | 'b'>,
144+
namedValue: LiteralUnion<AB>,
145+
array: readonly LiteralUnion<'a' | 'b'>[],
146+
namedArray: readonly LiteralUnion<AB>[],
147+
mixed: LiteralUnion<'a' | 'b'> | readonly LiteralUnion<'a' | 'b'>[],
148+
namedMixed: readonly LiteralUnion<AB>[] | LiteralUnion<AB>
149+
): string {
150+
return (
151+
value +
152+
namedValue +
153+
array.join('') +
154+
namedArray.join('') +
155+
String(mixed) +
156+
String(namedMixed)
157+
);
134158
}
135159

136160
/**

0 commit comments

Comments
 (0)