Skip to content

Commit 859093b

Browse files
aesteves60dpellier
aesteves60
authored and
dpellier
committed
docs(spec): remove unused + typage on typedoc json to md
1 parent 236bb64 commit 859093b

File tree

10 files changed

+356
-580
lines changed

10 files changed

+356
-580
lines changed

‎packages/common/core/src/utils/typedoc/typedoc-json-to-md.ts

+82-128
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
1-
type UnknownObject = Record<string, unknown>;
2-
type StringObject = Record<string, string>;
1+
import {
2+
DeclarationReflection,
3+
SomeType,
4+
LiteralType,
5+
IntrinsicType,
6+
ReflectionType,
7+
ReflectionKind,
8+
ReferenceType,
9+
} from 'typedoc';
310

411
const tableSeparator = '|';
512

6-
export function convertJsonToMarkdown(jsonItems: Record<string, unknown>[], filter: RegExp): string {
13+
export function convertJsonToMarkdown(jsonItems: DeclarationReflection[], filter: RegExp): string {
714
const result: string[] = [];
8-
const filteredItems = jsonItems.filter(({ name }) => (name as string).match(filter));
15+
const filteredItems = jsonItems.filter(({ name }) => name.match(filter));
916

1017
const displaySection = (stringArray: string[], sectionString: string) => {
1118
const res = stringArray;
@@ -17,29 +24,23 @@ export function convertJsonToMarkdown(jsonItems: Record<string, unknown>[], filt
1724

1825
const interfaces = getInterfaces(filteredItems),
1926
types = getTypes(filteredItems),
20-
classes = getClass(filteredItems),
21-
typeAlias = getTypeAlias(filteredItems),
22-
variables = getVariables(filteredItems);
27+
classes = getClass(filteredItems);
2328

2429
// Create Table
25-
result.push(
26-
...(interfaces?.length ? [`* [**Interfaces**](#interfaces)`] : []),
27-
...(types?.length ? [`* [**Types**](#types)`] : []),
28-
...(classes?.length ? [`* [**Classes**](#classes)`] : []),
29-
...(typeAlias?.length ? [`* [**Type alias**](#type-alias)`] : []),
30-
...(variables?.length ? [`* [**Variables**](#variables)`] : []),
30+
result.push(
31+
...(interfaces?.length ? [`* [**Interfaces**](#interfaces)`] : []),
32+
...(types?.length ? [`* [**Types**](#types)`] : []),
33+
...(classes?.length ? [`* [**Classes**](#classes)`] : []),
3134
);
3235

3336
displaySection(interfaces, `\n## Interfaces`);
3437
displaySection(types, `\n## Types`);
3538
displaySection(classes, `\n## Classes`);
36-
displaySection(typeAlias, `\n## Type alias`);
37-
displaySection(variables, `\n## Variables`);
3839

3940
return result.join('\n');
4041
}
4142

42-
function getInterfaces(filteredJSON: UnknownObject[]): string[] {
43+
function getInterfaces(filteredJSON: DeclarationReflection[]): string[] {
4344
const res: string[] = [];
4445

4546
filteredJSON.filter(({ kindString: filteredString, children: filteredChildren }) => filteredString === 'Interface'
@@ -48,26 +49,26 @@ function getInterfaces(filteredJSON: UnknownObject[]): string[] {
4849

4950
// Find default values
5051
const defaultValues: Record<string, string> = {};
51-
(((filteredJSON.find(({ kindString: defaultString, name: defaultName }) => defaultString === 'Variable'
52-
&& (defaultName as string).toLowerCase() === `${(name as string).toLowerCase()}defaultdoc`)
53-
?.type as UnknownObject)?.declaration as UnknownObject)?.children as UnknownObject[])
54-
?.forEach(({ name, defaultValue }) => {
55-
defaultValues[name as string] = defaultValue as string;
56-
});
52+
(filteredJSON.find(({ kindString: defaultString, name: defaultName }) => {
53+
return defaultString === 'Variable' && defaultName.toLowerCase() === `${name.toLowerCase()}defaultdoc`;
54+
}) as unknown as ReflectionType)
55+
?.declaration.children?.forEach(({ name, defaultValue }) => {
56+
defaultValues[name] = defaultValue?.toString() || '';
57+
});
5758

5859
res.push(
5960
tableSeparator + ['name', 'Type', 'Required', 'Default', 'Description'].join(` ${tableSeparator} `) + tableSeparator
6061
);
6162
res.push(
6263
tableSeparator + ['---', '---', ':---:', '---', '---'].join(`${tableSeparator}`) + tableSeparator
6364
);
64-
(children as UnknownObject[]).forEach(({ name, type, signatures, flags, comment }) => {
65-
const commentString: string = (comment as StringObject || (signatures && (signatures as Record<string, UnknownObject>[])[0]?.comment))?.shortText as unknown as string || '';
65+
children?.forEach(({ name, type, signatures, flags, comment }) => {
66+
const commentString: string = (comment || (signatures && signatures[0]?.comment))?.shortText as unknown as string || '';
6667
res.push(tableSeparator + [
6768
`**\`${name}\`**`,
68-
type ? printType(type as UnknownObject) : printType((signatures as UnknownObject[])[0]?.type as UnknownObject),
69-
!(flags as StringObject).isOptional ? '✴️' : '',
70-
defaultValues[name as string] ? `\`${defaultValues[name as string]}\`` : '',
69+
type ? printType(type) : printType(signatures?.[0]?.type),
70+
!flags.isOptional ? '✴️' : '',
71+
defaultValues[name] ? `\`${defaultValues[name]}\`` : '',
7172
commentString.replace(/\n/g, '')
7273
].join(` ${tableSeparator} `) + tableSeparator);
7374
});
@@ -76,131 +77,84 @@ function getInterfaces(filteredJSON: UnknownObject[]): string[] {
7677
return res;
7778
}
7879

79-
function getTypes(filteredJSON: UnknownObject[]): string[] {
80+
function getTypes(filteredJSON: DeclarationReflection[]): string[] {
8081
const res: string[] = [];
81-
filteredJSON.filter((item) => item.kindString === 'Enumeration').forEach((enumeration: UnknownObject) => {
82+
filteredJSON.filter((item) => item.kindString === 'Enumeration').forEach((enumeration: DeclarationReflection) => {
8283
res.push(`\n### ${enumeration.name}`);
8384
res.push(`| |\n|:---:|`);
8485
if (enumeration.children) {
85-
res.push((enumeration.children as UnknownObject[]).map((property) => `| \`${property.name}\` |`).join('\n'));
86+
res.push(enumeration.children.map((property) => `| \`${property.name}\` |`).join('\n'));
8687
}
8788
});
8889
return res;
8990
}
9091

91-
function getClass(filteredJSON: UnknownObject[]): string[] {
92+
function getClass(filteredJSON: DeclarationReflection[]): string[] {
9293
const res: string[] = [];
93-
filteredJSON.filter((item) => item.kindString === 'Class').forEach(({
94-
name: className,
95-
comment: classComment,
96-
children: classChildren,
97-
}) => {
98-
res.push(`\n### ${className}`);
99-
const comments = (classComment as UnknownObject)?.shortText as string;
94+
filteredJSON.filter((item) => item.kindString === 'Class').forEach((typeDocClass) => {
95+
res.push(`\n### ${typeDocClass.name}`);
96+
const comments = typeDocClass.comment?.shortText;
10097
if(comments) {
10198
res.push(`_${comments.replace(/\n/gmi, '_\n_')}_\n`);
10299
}
103100

104101
// Methods
105-
const methods = (classChildren as UnknownObject[])?.filter((item) => item.kindString === 'Method');
106-
if (typeof methods !== 'undefined' && methods.length) {
107-
res.push(`#### Methods`);
108-
methods.forEach(({ signatures: methodSignatures, name: methodName }) => {
109-
const { signatureParameters, signatureType, signatureComment } = (methodSignatures as UnknownObject[])[0];
110-
const params: string[] = [];
111-
const parameterSection: string[] = [];
112-
if (signatureParameters && (signatureParameters as UnknownObject[]).length) {
113-
parameterSection.push(`Name | Type | Description \n---|---|---`);
114-
(signatureParameters as UnknownObject[])?.map(({
115-
name: paramName,
116-
type: paramType,
117-
comment: paramComment,
118-
}) => {
119-
params.push(`\`${paramName}\`: ${printType(paramType as UnknownObject)}`);
120-
parameterSection.push(`**${paramName}** | ${printType(paramType as UnknownObject)} | ${(paramComment as StringObject)?.shortText}`);
121-
});
122-
}
123-
res.push(`> **${methodName}**(${(params || ['']).join(',')}) => ${printType(signatureType as UnknownObject)}\n`);
124-
const comments = ((signatureComment as UnknownObject)?.shortText as string);
125-
if(comments) {
126-
res.push(`_${comments.replace(/\n/gmi, '_\n_')}_\n`);
127-
}
128-
res.push(`${(parameterSection || ['']).join('\n')}`);
129-
});
130-
}
131-
});
132-
133-
return res;
134-
}
135-
136-
function getTypeAlias(filteredJSON: UnknownObject[]): string[] {
137-
const res: string[] = [];
138-
filteredJSON.filter(({ kindString: itemString, type: itemType }) => itemString === 'Type alias'
139-
&& (itemType as UnknownObject).type !== 'template-literal').forEach(({
140-
name: typeAliasName,
141-
comment: typeAliasComment,
142-
type: typeAliasType,
143-
typeParameter: typeAliasTypeParameter,
144-
}) => {
145-
res.push(`\n### ${typeAliasName}`);
146-
if (typeAliasComment) {
147-
res.push(`\n${(typeAliasComment as UnknownObject)?.shortText}`);
102+
const methods = typeDocClass.children?.filter((method) => method.kind === ReflectionKind.Method)
103+
.filter((method) => method.decorators?.[0].name === 'Method' && (method.decorators?.[0].type as ReferenceType)?.package === '@stencil/core');
104+
if (!methods?.length) {
105+
return;
148106
}
149-
150-
switch ((typeAliasType as UnknownObject).type) {
151-
case 'reference':
152-
((typeAliasTypeParameter || (typeAliasType as UnknownObject).typeArguments) as UnknownObject[])?.map((typeParameter) => {
153-
res.push(`\n> - ${printType(typeParameter as UnknownObject) !== '_unknown_' ?
154-
printType(typeParameter as UnknownObject) :
155-
printType(typeParameter.type as UnknownObject)}`
156-
);
107+
res.push(`#### Methods`);
108+
methods.forEach(({ signatures: methodSignatures, name: methodName }) => {
109+
if (!methodSignatures?.[0]) {
110+
return;
111+
}
112+
const { parameters, type, comment } = methodSignatures[0];
113+
const params: string[] = [];
114+
const parameterSection: string[] = [];
115+
if (parameters && parameters.length) {
116+
parameterSection.push(`Name | Type | Description \n---|---|---`);
117+
parameters?.map(({name: paramName, type: paramType, comment: paramComment }) => {
118+
params.push(`\`${paramName}\`: ${printType(paramType)}`);
119+
parameterSection.push(`**${paramName}** | ${printType(paramType)} | ${paramComment?.shortText || ''}`);
157120
});
158-
break;
159-
case 'union':
160-
((typeAliasType as UnknownObject).types as UnknownObject[]).forEach((typeVariant) => {
161-
res.push(`\n> - ${printType(typeVariant)}`);
162-
});
163-
break;
164-
}
165-
});
166-
filteredJSON.filter((item) => item.kindString === 'Interface'
167-
&& typeof item.extendedTypes !== 'undefined'
168-
&& (item.extendedTypes as UnknownObject[])[0]?.type === 'reference').forEach(({
169-
name: typeAliasName,
170-
extendedTypes: typeAliasExtendedTypes,
171-
}) => {
172-
173-
res.push(`\n### ${typeAliasName}`);
174-
res.push(`\n> _Based on ${printType((typeAliasExtendedTypes as UnknownObject[])[0])}_`);
175-
});
176-
return res;
177-
}
178-
179-
function getVariables(filteredJSON: UnknownObject[]): string[] {
180-
const res: string[] = [];
181-
filteredJSON
182-
.filter(({
183-
kindString: itemString,
184-
type: itemType,
185-
}) => itemString === 'Variable' && (itemType as UnknownObject).type !== 'array' && (itemType as UnknownObject).type !== 'reflection')
186-
.forEach(({ name: variableName, type: variableType }) => {
187-
res.push(`\n### ${variableName}`);
188-
res.push(`${printType(variableType as UnknownObject)}`);
121+
}
122+
res.push(`> **${methodName}**(${(params || ['']).join(',')}) => ${printType(type)}\n`);
123+
const comments = comment?.shortText;
124+
if(comments) {
125+
res.push(`_${comments.replace(/\n/gmi, '_\n_')}_\n`);
126+
}
127+
res.push(`${(parameterSection || ['']).join('\n')}`);
189128
});
129+
});
130+
190131
return res;
191132
}
192133

193-
function printType(typeObject: UnknownObject) {
194-
const getTypeValue = (tObj: UnknownObject) => typeof tObj.name !== 'undefined' ? `${tObj.name}` : `${tObj.value}`;
195-
if (typeObject && typeObject.type) {
196-
switch (typeObject.type) {
134+
function printType(typeObject?: SomeType | unknown) {
135+
const getTypeValue = (tObj: SomeType | LiteralType | IntrinsicType) => {
136+
if ('name' in tObj) {
137+
return tObj.name.toString();
138+
}
139+
if ('value' in tObj) {
140+
return tObj.value?.toString();
141+
}
142+
return tObj.type
143+
};
144+
const someType = typeObject as SomeType;
145+
if (someType && someType.type) {
146+
switch (someType.type) {
197147
case 'intrinsic':
198148
case 'literal':
199-
return `_${getTypeValue(typeObject)}_`;
200-
case 'reference':
201-
return `\`${typeObject.name}\``;
149+
return `_${getTypeValue(someType)}_`;
150+
case 'reference': {
151+
if (someType.name === 'Promise') {
152+
return `\`${someType.name}<${getTypeValue(someType.typeArguments?.[0] as IntrinsicType)}>\``;
153+
}
154+
return `\`${someType.name}\``;
155+
}
202156
case 'union':
203-
return (typeObject.types as UnknownObject[]).map((tObj) => `\`${getTypeValue(tObj)}\``).join(' \\| ');
157+
return someType.types.map((tObj) => `\`${getTypeValue(tObj)}\``).join(' \\| ');
204158
}
205159
}
206160
return '_unknown_';

‎packages/components/accordion/documentation/specifications/accordionGroupSpec.md

-81
This file was deleted.

0 commit comments

Comments
 (0)