Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: fix unwrap literal union #1752

Merged
merged 12 commits into from
Jan 26, 2023
Merged

docs: fix unwrap literal union #1752

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2a063a9
docs: unwrap literal union
ST-DDT Jan 18, 2023
7b9ae7c
chore: apply suggestions
ST-DDT Jan 18, 2023
a8e37a5
chore: attempt to remove readonly
ST-DDT Jan 18, 2023
526b4c9
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 18, 2023
108ffde
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 21, 2023
71320e4
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 22, 2023
e07b498
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 23, 2023
f3a624b
test: update snapshots
ST-DDT Jan 23, 2023
310c78c
docs: wrap functions in parenthesis
ST-DDT Jan 23, 2023
4685797
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 24, 2023
5cf003a
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 24, 2023
4a722db
Merge branch 'next' into docs/unwrap-literal-union
ST-DDT Jan 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions scripts/apidoc/signature.ts
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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