Skip to content

Commit

Permalink
docs: fix unwrap literal union (#1752)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ST-DDT
ST-DDT authored Jan 26, 2023
1 parent b86638d commit dcb318f
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 9 deletions.
29 changes: 25 additions & 4 deletions scripts/apidoc/signature.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -277,20 +277,29 @@ function typeToText(type_?: Type, short = false): string {

const type = type_ as SomeType;
switch (type.type) {
case 'array':
return `${typeToText(type.elementType, short)}[]`;
case 'array': {
const text = typeToText(type.elementType, short);
if (text.includes('|') || text.includes('{')) {
return `Array<${text}>`;
} else {
return `${text}[]`;
}
}

case 'union':
return type.types
.map((t) => typeToText(t, short))
.map((t) => (t.includes('=>') ? `(${t})` : t))
.sort()
.join(' | ');

case 'reference':
if (!type.typeArguments || !type.typeArguments.length) {
return type.name;
} else if (type.name === 'LiteralUnion') {
return [
typeToText(type.typeArguments[0]),
typeToText(type.typeArguments[1]),
typeToText(type.typeArguments[0], short),
typeToText(type.typeArguments[1], short),
].join(' | ');
} else {
return `${type.name}<${type.typeArguments
Expand All @@ -300,13 +309,25 @@ function typeToText(type_?: Type, short = false): string {

case 'reflection':
return declarationTypeToText(type.declaration, short);

case 'indexedAccess':
return `${typeToText(type.objectType, short)}[${typeToText(
type.indexType,
short
)}]`;

case 'literal':
return formatTypescript(type.toString()).replace(/;\n$/, '');

case 'typeOperator': {
const text = typeToText(type.target, short);
if (short && type.operator === 'readonly') {
return text;
} else {
return `${type.operator} ${text}`;
}
}

default:
return type.toString();
}
Expand Down
44 changes: 41 additions & 3 deletions test/scripts/apidoc/__snapshots__/signature.spec.ts.snap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
"deprecated": false,
"description": "<p>Complex array parameter.</p>
",
"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>
"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>
<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>
<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>
<span class=\\"line\\"><span style=\\"color:#89DDFF\\">}&gt;</span><span style=\\"color:#A6ACCD\\">): T</span></span>
<span class=\\"line\\"></span></code></pre>
</div>",
"name": "complexArrayParameter",
Expand All @@ -21,7 +24,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
"description": "<p>Array to pick the value from.</p>
",
"name": "array",
"type": "readonly Object[]",
"type": "Array<{ ... }>",
},
{
"default": undefined,
Expand Down Expand Up @@ -123,7 +126,7 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
"deprecated": false,
"description": "<p>Test with LiteralUnion.</p>
",
"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>
"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>
<span class=\\"line\\"></span></code></pre>
</div>",
"name": "literalUnionParamMethod",
Expand All @@ -135,6 +138,41 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = `
"name": "value",
"type": "'a' | 'b' | string",
},
{
"default": undefined,
"description": "<p><code>'a'</code> or <code>'b'</code>.</p>
",
"name": "namedValue",
"type": "AB | string",
},
{
"default": undefined,
"description": "<p>Array of <code>'a'</code> or <code>'b'</code>.</p>
",
"name": "array",
"type": "Array<'a' | 'b' | string>",
},
{
"default": undefined,
"description": "<p>Array of <code>'a'</code> or <code>'b'</code>.</p>
",
"name": "namedArray",
"type": "Array<AB | string>",
},
{
"default": undefined,
"description": "<p>Value <code>'a'</code> or <code>'b'</code> or an array thereof.</p>
",
"name": "mixed",
"type": "'a' | 'b' | string | Array<'a' | 'b' | string>",
},
{
"default": undefined,
"description": "<p>Value <code>'a'</code> or <code>'b'</code> or an array thereof.</p>
",
"name": "namedMixed",
"type": "AB | string | Array<AB | string>",
},
],
"returns": "string",
"seeAlsos": [],
Expand Down
28 changes: 26 additions & 2 deletions test/scripts/apidoc/signature.example.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,11 @@ export interface ParameterOptionsInterfaceC {
value?: number;
}

/**
* A or B.
*/
export type AB = 'a' | 'b';

export class SignatureTest {
/**
* Test with no parameters.
Expand Down Expand Up @@ -128,9 +133,28 @@ export class SignatureTest {
* Test with LiteralUnion.
*
* @param value `'a'` or `'b'`.
* @param namedValue `'a'` or `'b'`.
* @param array Array of `'a'` or `'b'`.
* @param namedArray Array of `'a'` or `'b'`.
* @param mixed Value `'a'` or `'b'` or an array thereof.
* @param namedMixed Value `'a'` or `'b'` or an array thereof.
*/
literalUnionParamMethod(value: LiteralUnion<'a' | 'b'>): string {
return value;
literalUnionParamMethod(
value: LiteralUnion<'a' | 'b'>,
namedValue: LiteralUnion<AB>,
array: readonly LiteralUnion<'a' | 'b'>[],
namedArray: readonly LiteralUnion<AB>[],
mixed: LiteralUnion<'a' | 'b'> | readonly LiteralUnion<'a' | 'b'>[],
namedMixed: readonly LiteralUnion<AB>[] | LiteralUnion<AB>
): string {
return (
value +
namedValue +
array.join('') +
namedArray.join('') +
String(mixed) +
String(namedMixed)
);
}

/**
Expand Down

0 comments on commit dcb318f

Please sign in to comment.