1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
import type { DeclarationReflection, ProjectReflection } from 'typedoc';
import { ReflectionKind } from 'typedoc';
import type { Method } from '../../docs/.vitepress/components/api-docs/method';
import { faker } from '../../src';
import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter';
import { analyzeSignature, toBlock } from './signature';
import type { PageIndex } from './utils';
/**
* Selects the modules from the project that needs to be documented.
*
* @param project The project used to extract the modules.
* @returns The modules to document.
*/
export function selectApiModules(
project: ProjectReflection
): DeclarationReflection[] {
return project
.getChildrenByKind(ReflectionKind.Class)
.filter((module) => faker[extractModuleFieldName(module)] != null);
}
/**
* Analyzes and writes the documentation for modules and their methods such as `faker.animal.cat()`.
*
* @param project The project used to extract the modules.
* @returns The generated pages.
*/
export function processModuleMethods(project: ProjectReflection): PageIndex {
const pages: PageIndex = [];
// Generate module files
for (const module of selectApiModules(project)) {
pages.push(...processModuleMethod(module));
}
return pages;
}
export function extractModuleName(module: DeclarationReflection): string {
const { name } = module;
// TODO @ST-DDT 2022-10-16: Remove in v10.
// Typedoc prefers the name of the module that is exported first.
if (name === 'AddressModule') {
return 'Location';
} else if (name === 'NameModule') {
return 'Person';
}
return name.replace(/Module$/, '');
}
function extractModuleFieldName(module: DeclarationReflection): string {
const moduleName = extractModuleName(module);
return moduleName.substring(0, 1).toLowerCase() + moduleName.substring(1);
}
/**
* Analyzes and writes the documentation for a module and its methods such as `faker.animal.cat()`.
*
* @param module The module to process.
* @returns The generated pages.
*/
function processModuleMethod(module: DeclarationReflection): PageIndex {
const moduleName = extractModuleName(module);
const moduleFieldName = extractModuleFieldName(module);
console.log(`Processing Module ${moduleName}`);
const methods: Method[] = [];
// Generate method section
for (const method of module.getChildrenByKind(ReflectionKind.Method)) {
const methodName = method.name;
console.debug(`- ${methodName}`);
const signatures = method.signatures;
const signature = signatures[signatures.length - 1];
methods.push(analyzeSignature(signature, moduleFieldName, methodName));
}
writeApiDocsModulePage(
moduleName,
moduleFieldName,
toBlock(module.comment),
methods
);
writeApiDocsData(moduleFieldName, methods);
return [
{
text: moduleName,
link: `/api/${moduleFieldName}.html`,
},
];
}
|
