Skip to content

Commit f76d682

Browse files
normanzbnormanzb
committed
fix(core): format of optional type and getter/setter
1 parent 7032ebd commit f76d682

File tree

9 files changed

+96
-54
lines changed

9 files changed

+96
-54
lines changed

‎package-lock.json

+6-6
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureParameters.ts

+17-10
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
import { backTicks } from '@plugin/libs/markdown/index.js';
1+
import { backTicks as rawBackTicks } from '@plugin/libs/markdown/index.js';
22
import { MarkdownThemeContext } from '@plugin/theme/index.js';
33
import { ParameterReflection, SomeType } from 'typedoc';
44

55
export function signatureParameters(
66
this: MarkdownThemeContext,
77
model: ParameterReflection[],
8+
options?: { forceExpandParameters?: boolean; avoidBackTicks?: boolean },
89
) {
10+
const backTicks = options?.avoidBackTicks
11+
? (str: string) => str
12+
: rawBackTicks;
913
const format = this.options.getValue('useCodeBlocks');
1014
const firstOptionalParamIndex = model.findIndex(
1115
(parameter) => parameter.flags.isOptional,
@@ -18,15 +22,18 @@ export function signatureParameters(
1822
if (param.flags?.isRest) {
1923
paramsmd.push('...');
2024
}
21-
const paramType = this.partials.someType(param.type as SomeType);
22-
const showParamType = this.options.getValue('expandParameters');
23-
const optional = param.flags.isOptional ||
24-
(firstOptionalParamIndex !== -1 && i > firstOptionalParamIndex)
25-
? '?'
26-
: ''
27-
const paramItem = [
28-
`${backTicks(`${param.name}${optional}`)}`,
29-
];
25+
const paramType = this.partials.someType(param.type as SomeType, {
26+
avoidBackTicks: options?.avoidBackTicks,
27+
});
28+
const showParamType =
29+
(options?.forceExpandParameters ?? false) ||
30+
this.options.getValue('expandParameters');
31+
const optional =
32+
param.flags.isOptional ||
33+
(firstOptionalParamIndex !== -1 && i > firstOptionalParamIndex)
34+
? '?'
35+
: '';
36+
const paramItem = [`${backTicks(`${param.name}${optional}`)}`];
3037
if (showParamType) {
3138
paramItem.push(paramType);
3239
}

‎packages/typedoc-plugin-markdown/src/theme/context/partials/type.intrinsic.ts

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1-
import { backTicks } from '@plugin/libs/markdown/index.js';
1+
import { backTicks as rawBackTicks } from '@plugin/libs/markdown/index.js';
22
import { MarkdownThemeContext } from '@plugin/theme/index.js';
33
import { IntrinsicType } from 'typedoc';
44

55
export function intrinsicType(
66
this: MarkdownThemeContext,
77
model: IntrinsicType,
8+
options?: { avoidBackTicks?: boolean | undefined },
89
): string {
10+
const backTicks = options?.avoidBackTicks
11+
? (str: string) => str
12+
: rawBackTicks;
913
return backTicks(model.name);
1014
}

‎packages/typedoc-plugin-markdown/src/theme/context/partials/type.reflection.declaration.ts

+13-7
Original file line numberDiff line numberDiff line change
@@ -41,16 +41,22 @@ export function declarationType(
4141

4242
if (obj.getSignature) {
4343
name.push('get');
44-
name.push(backTicks(obj.name) + '\n ');
45-
}
46-
47-
if (obj.setSignature) {
44+
name.push(backTicks(obj.name + '()'));
45+
} else if (obj.setSignature) {
4846
name.push('set');
49-
name.push(backTicks(obj.name));
47+
const params = obj.setSignature.parameters
48+
? this.partials.signatureParameters(obj.setSignature.parameters, {
49+
forceExpandParameters: true,
50+
avoidBackTicks: true,
51+
})
52+
: '()';
53+
name.push(backTicks(obj.name + params));
54+
} else {
55+
const displayObjectName =
56+
obj.name + (obj.flags?.isOptional ? '?' : '');
57+
name.push(backTicks(displayObjectName));
5058
}
5159

52-
name.push(backTicks(obj.name));
53-
5460
const theType = this.helpers.getDeclarationType(obj) as SomeType;
5561

5662
const typeString = this.partials.someType(theType, options);

‎packages/typedoc-plugin-markdown/src/theme/context/partials/type.some.ts

+12-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { backTicks } from '@plugin/libs/markdown/index.js';
1+
import { backTicks as rawBackTicks } from '@plugin/libs/markdown/index.js';
22
import { MarkdownThemeContext } from '@plugin/theme/index.js';
33
import {
44
ArrayType,
@@ -22,8 +22,12 @@ import {
2222
export function someType(
2323
this: MarkdownThemeContext,
2424
model?: SomeType,
25-
options?: { forceCollapse?: boolean },
25+
options?: { forceCollapse?: boolean; avoidBackTicks?: boolean },
2626
): string {
27+
const backTicks = options?.avoidBackTicks
28+
? (str: string) => str
29+
: rawBackTicks;
30+
2731
if (!model) {
2832
return '';
2933
}
@@ -49,7 +53,9 @@ export function someType(
4953
}
5054

5155
if (model instanceof IntrinsicType && model.name) {
52-
return this.partials.intrinsicType(model);
56+
return this.partials.intrinsicType(model, {
57+
avoidBackTicks: options?.avoidBackTicks,
58+
});
5359
}
5460

5561
if (model instanceof QueryType) {
@@ -75,7 +81,9 @@ export function someType(
7581
}
7682

7783
if (model instanceof UnionType && model.types) {
78-
return this.partials.unionType(model);
84+
return this.partials.unionType(model, {
85+
avoidBackTicks: options?.avoidBackTicks,
86+
});
7987
}
8088

8189
if (model instanceof UnknownType) {

‎packages/typedoc-plugin-markdown/src/theme/context/partials/type.union.ts

+5-1
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,14 @@ import { UnionType } from 'typedoc';
44
export function unionType(
55
this: MarkdownThemeContext,
66
model: UnionType,
7+
options?: { avoidBackTicks?: boolean | undefined },
78
): string {
89
const useCodeBlocks = this.options.getValue('useCodeBlocks');
910
const typesOut = model.types.map((unionType) =>
10-
this.partials.someType(unionType, { forceCollapse: true }),
11+
this.partials.someType(unionType, {
12+
forceCollapse: true,
13+
avoidBackTicks: options?.avoidBackTicks,
14+
}),
1115
);
1216
const shouldFormat =
1317
useCodeBlocks &&

‎packages/typedoc-plugin-markdown/src/theme/context/resources.ts

+24-7
Original file line numberDiff line numberDiff line change
@@ -160,8 +160,16 @@ There is no association list partial for properties as these are handled as a st
160160
hideTitle?: boolean | undefined;
161161
},
162162
) => partials.signature.apply(context, [model, options]) as string,
163-
signatureParameters: (model: ParameterReflection[]) =>
164-
partials.signatureParameters.apply(context, [model]) as string,
163+
signatureParameters: (
164+
model: ParameterReflection[],
165+
options?:
166+
| {
167+
forceExpandParameters?: boolean | undefined;
168+
avoidBackTicks?: boolean | undefined;
169+
}
170+
| undefined,
171+
) =>
172+
partials.signatureParameters.apply(context, [model, options]) as string,
165173
signatureReturns: (
166174
model: SignatureReflection,
167175
options: { headingLevel: number },
@@ -244,8 +252,10 @@ There is no association list partial for properties as these are handled as a st
244252
partials.inferredType.apply(context, [model]) as string,
245253
intersectionType: (model: IntersectionType) =>
246254
partials.intersectionType.apply(context, [model]) as string,
247-
intrinsicType: (model: IntrinsicType) =>
248-
partials.intrinsicType.apply(context, [model]) as string,
255+
intrinsicType: (
256+
model: IntrinsicType,
257+
options?: { avoidBackTicks?: boolean | undefined } | undefined,
258+
) => partials.intrinsicType.apply(context, [model, options]) as string,
249259
literalType: (model: LiteralType) =>
250260
partials.literalType.apply(context, [model]) as string,
251261
namedTupleType: (model: NamedTupleMember) =>
@@ -277,14 +287,21 @@ There is no association list partial for properties as these are handled as a st
277287
) => partials.reflectionType.apply(context, [model, options]) as string,
278288
someType: (
279289
model?: SomeType | undefined,
280-
options?: { forceCollapse?: boolean | undefined } | undefined,
290+
options?:
291+
| {
292+
forceCollapse?: boolean | undefined;
293+
avoidBackTicks?: boolean | undefined;
294+
}
295+
| undefined,
281296
) => partials.someType.apply(context, [model, options]) as string,
282297
tupleType: (model: TupleType) =>
283298
partials.tupleType.apply(context, [model]) as string,
284299
typeOperatorType: (model: TypeOperatorType) =>
285300
partials.typeOperatorType.apply(context, [model]) as string,
286-
unionType: (model: UnionType) =>
287-
partials.unionType.apply(context, [model]) as string,
301+
unionType: (
302+
model: UnionType,
303+
options?: { avoidBackTicks?: boolean | undefined } | undefined,
304+
) => partials.unionType.apply(context, [model, options]) as string,
288305
unknownType: (model: UnknownType) =>
289306
partials.unknownType.apply(context, [model]) as string,
290307
};

‎packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap

+12-16
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ Comments for propWithFunction
151151
152152
### propWithProps
153153
154-
> **propWithProps**: \\{ \`callbacks\`: \`Partial\`\\<[\`CallbacksOptions\`](../classes/CallbacksOptions.md)\\<[\`DisposableClass\`](../classes/DisposableClass.md), [\`ClassWithModifiers\`](../classes/ClassWithModifiers.md)\\>\\>; \`nestedPropA\`: \`string\`; \`nestedPropB\`: \`boolean\`; \`nestedPropC\`: \\{ \`nestedPropCA\`: \`string\`; \\}; \`nestedPropD\`: () => \`boolean\`; \\}
154+
> **propWithProps**: \\{ \`callbacks?\`: \`Partial\`\\<[\`CallbacksOptions\`](../classes/CallbacksOptions.md)\\<[\`DisposableClass\`](../classes/DisposableClass.md), [\`ClassWithModifiers\`](../classes/ClassWithModifiers.md)\\>\\>; \`nestedPropA\`: \`string\`; \`nestedPropB\`: \`boolean\`; \`nestedPropC\`: \\{ \`nestedPropCA\`: \`string\`; \\}; \`nestedPropD\`: () => \`boolean\`; \\}
155155
156156
Comments for propWithProps
157157
@@ -221,7 +221,7 @@ Comments for BasicInterface
221221
| <a id="propreturningsignaturedeclaration"></a> \`propReturningSignatureDeclaration?\` | () => \`string\` \\| \`number\` \\| \`boolean\` | Comments for propReturningSignatureDeclaration |
222222
| <a id="propreturningsignaturedeclarations"></a> \`propReturningSignatureDeclarations\` | () => \`any\` & (\`paramsA\`: \`true\` \\| \`any\`[], \`paramsB?\`: \`any\`) => \`any\` & (\`paramsC\`: \`any\`) => \`any\` | Comments for propReturningSignatureDeclarations |
223223
| <a id="propwithfunction"></a> \`propWithFunction\` | (\`options\`: \\{ \`a\`: \`boolean\`; \`b\`: \`string\`; \\}) => \`boolean\` | Comments for propWithFunction |
224-
| <a id="propwithprops"></a> \`propWithProps\` | \\{ \`callbacks\`: \`Partial\`\\<[\`CallbacksOptions\`](../classes/CallbacksOptions.md)\\<[\`DisposableClass\`](../classes/DisposableClass.md), [\`ClassWithModifiers\`](../classes/ClassWithModifiers.md)\\>\\>; \`nestedPropA\`: \`string\`; \`nestedPropB\`: \`boolean\`; \`nestedPropC\`: \\{ \`nestedPropCA\`: \`string\`; \\}; \`nestedPropD\`: () => \`boolean\`; \\} | Comments for propWithProps |
224+
| <a id="propwithprops"></a> \`propWithProps\` | \\{ \`callbacks?\`: \`Partial\`\\<[\`CallbacksOptions\`](../classes/CallbacksOptions.md)\\<[\`DisposableClass\`](../classes/DisposableClass.md), [\`ClassWithModifiers\`](../classes/ClassWithModifiers.md)\\>\\>; \`nestedPropA\`: \`string\`; \`nestedPropB\`: \`boolean\`; \`nestedPropC\`: \\{ \`nestedPropCA\`: \`string\`; \\}; \`nestedPropD\`: () => \`boolean\`; \\} | Comments for propWithProps |
225225
| \`propWithProps.callbacks?\` | \`Partial\`\\<[\`CallbacksOptions\`](../classes/CallbacksOptions.md)\\<[\`DisposableClass\`](../classes/DisposableClass.md), [\`ClassWithModifiers\`](../classes/ClassWithModifiers.md)\\>\\> | Comments for callbacks |
226226
| \`propWithProps.nestedPropA\` | \`string\` | Comments for nestedPropA |
227227
| \`propWithProps.nestedPropB\` | \`boolean\` | Comments for nestedPropB |
@@ -362,7 +362,7 @@ y: number = 2;
362362
exports[`Objects And Params should compile function with nested parameters: (Output File Strategy "members") (Option Group "1") 1`] = `
363363
"# Function: functionWithNestedParameters()
364364
365-
> **functionWithNestedParameters**(\`params\`: \\{ \`name\`: \`string\`; \`nestedObj\`: \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\}; \`parent\`: \`number\`; \\}, \`context\`: \`any\`, \`somethingElse?\`: \`string\`): \`boolean\`
365+
> **functionWithNestedParameters**(\`params\`: \\{ \`name\`: \`string\`; \`nestedObj\`: \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\}; \`parent?\`: \`number\`; \\}, \`context\`: \`any\`, \`somethingElse?\`: \`string\`): \`boolean\`
366366
367367
Some nested params.
368368
@@ -434,7 +434,7 @@ function functionWithNestedParameters(
434434
};
435435
value: number;
436436
};
437-
parent: number;
437+
parent?: number;
438438
},
439439
context: any,
440440
somethingElse?: string): boolean;
@@ -446,7 +446,7 @@ Some nested params.
446446
447447
| Parameter | Type | Description |
448448
| :------ | :------ | :------ |
449-
| \`params\` | \\{ \`name\`: \`string\`; \`nestedObj\`: \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\}; \`parent\`: \`number\`; \\} | The parameters passed to the method. |
449+
| \`params\` | \\{ \`name\`: \`string\`; \`nestedObj\`: \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\}; \`parent?\`: \`number\`; \\} | The parameters passed to the method. |
450450
| \`params.name\` | \`string\` | The name of the new group. |
451451
| \`params.nestedObj\` | \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\} | A nested object. |
452452
| \`params.nestedObj.name?\` | \`string\` | - |
@@ -502,9 +502,7 @@ bar: number;
502502
exports[`Objects And Params should compile literal type: (Output File Strategy "members") (Option Group "1") 1`] = `
503503
"# Type Alias: LiteralType
504504
505-
> **LiteralType** = \\{ \`someFunctionWithArrow\`: () => \`string\`; \`x\`: \`string\`; \`y\`: \\{ \`x\`: \`string\`; \`y\`: \`boolean\` \\| \`string\`; \`z\`: (\`x\`: \`string\`) => \`string\`; \\}; \`z\`: (\`x\`: \`string\`) => \`string\`; get \`accessorA\`
506-
set \`accessorA\` \`accessorA\`: [\`Promise\`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\\<\`string\`\\>; get \`accessorB\`
507-
set \`accessorB\` \`accessorB\`: \`string\`; \`someFunction\`: [\`Promise\`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\\<\`any\`\\>; \\}
505+
> **LiteralType** = \\{ \`someFunctionWithArrow\`: () => \`string\`; \`x?\`: \`string\`; \`y\`: \\{ \`x\`: \`string\`; \`y?\`: \`boolean\` \\| \`string\`; \`z\`: (\`x\`: \`string\`) => \`string\`; \\}; \`z\`: (\`x\`: \`string\`) => \`string\`; get \`accessorA()\`: [\`Promise\`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\\<\`string\`\\>; get \`accessorB()\`: \`string\`; \`someFunction\`: [\`Promise\`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\\<\`any\`\\>; \\}
508506
509507
Comments for LiteralType
510508
@@ -532,7 +530,7 @@ comment for x
532530
533531
### y
534532
535-
> **y**: \\{ \`x\`: \`string\`; \`y\`: \`boolean\` \\| \`string\`; \`z\`: (\`x\`: \`string\`) => \`string\`; \\}
533+
> **y**: \\{ \`x\`: \`string\`; \`y?\`: \`boolean\` \\| \`string\`; \`z\`: (\`x\`: \`string\`) => \`string\`; \\}
536534
537535
comment for y
538536
@@ -662,17 +660,15 @@ exports[`Objects And Params should compile literal type: (Output File Strategy "
662660
\`\`\`ts
663661
type LiteralType = {
664662
someFunctionWithArrow: () => string;
665-
x: string;
663+
x?: string;
666664
y: {
667665
x: string;
668-
y: boolean | string;
666+
y?: boolean | string;
669667
z: (x: string) => string;
670668
};
671669
z: (x: string) => string;
672-
get accessorA
673-
set accessorA accessorA: Promise<string>;
674-
get accessorB
675-
set accessorB accessorB: string;
670+
get accessorA(): Promise<string>;
671+
get accessorB(): string;
676672
someFunction: Promise<any>;
677673
};
678674
\`\`\`
@@ -710,7 +706,7 @@ comment for x
710706
\`\`\`ts
711707
y: {
712708
x: string;
713-
y: boolean | string;
709+
y?: boolean | string;
714710
z: (x: string) => string;
715711
};
716712
\`\`\`

‎packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap

+2-2
Original file line numberDiff line numberDiff line change
@@ -1101,7 +1101,7 @@ Defined in: [functions.ts:1](http://source-url)
11011101
11021102
| Parameter | Type | Description |
11031103
| :------ | :------ | :------ |
1104-
| \`__namedParameters\` | \\{ \`bar\`: \`number\`; \`foo\`: \`number\`; \\} | various options |
1104+
| \`__namedParameters\` | \\{ \`bar?\`: \`number\`; \`foo?\`: \`number\`; \\} | various options |
11051105
| \`__namedParameters.bar?\` | \`number\` | - |
11061106
| \`__namedParameters.foo?\` | \`number\` | - |
11071107
| \`anotherParam\` | \`string\` | Another param comment |
@@ -1193,7 +1193,7 @@ Some nested params.
11931193
11941194
| Parameter | Type | Description |
11951195
| :------ | :------ | :------ |
1196-
| \`params\` | \\{ \`name\`: \`string\`; \`nestedObj\`: \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\}; \`parent\`: \`number\`; \\} | The parameters passed to the method. |
1196+
| \`params\` | \\{ \`name\`: \`string\`; \`nestedObj\`: \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\}; \`parent?\`: \`number\`; \\} | The parameters passed to the method. |
11971197
| \`params.name\` | \`string\` | The name of the new group. |
11981198
| \`params.nestedObj\` | \\{ \`name\`: \`string\`; \`obj\`: \\{ \`name\`: () => \`void\`; \\}; \`value\`: \`number\`; \\} | A nested object. |
11991199
| \`params.nestedObj.name?\` | \`string\` | - |

0 commit comments

Comments
 (0)