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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
import type {
DeclarationReflection,
ProjectReflection,
SignatureReflection,
} from 'typedoc';
import type { Method } from '../../docs/.vitepress/components/api-docs/method';
import { writeApiDocsModule } from './apiDocsWriter';
import { codeToHtml } from './markdown';
import { analyzeSignature } from './signature';
import {
extractDeprecated,
extractDescription,
extractJoinedRawExamples,
extractModuleFieldName,
extractModuleName,
selectApiMethodSignatures,
selectApiModules,
} from './typedoc';
import type { ModuleSummary } from './utils';
import { adjustUrls } from './utils';
/**
* 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 async function processModules(
project: ProjectReflection
): Promise<ModuleSummary[]> {
return Promise.all(selectApiModules(project).map(processModule));
}
/**
* 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.
*/
async function processModule(
module: DeclarationReflection
): Promise<ModuleSummary> {
const moduleName = extractModuleName(module);
console.log(`Processing Module ${moduleName}`);
const moduleFieldName = extractModuleFieldName(module);
const { comment, deprecated, examples } = analyzeModule(module);
const methods = await processModuleMethods(
module,
`faker.${moduleFieldName}.`
);
return writeApiDocsModule(
moduleName,
moduleFieldName,
comment,
examples,
deprecated,
methods
);
}
/**
* Analyzes the documentation for a class.
*
* @param module The class to process.
* @returns The class information.
*/
export function analyzeModule(module: DeclarationReflection): {
comment: string;
deprecated: string | undefined;
examples: string | undefined;
} {
const examplesRaw = extractJoinedRawExamples(module);
const examples = examplesRaw ? codeToHtml(examplesRaw) : undefined;
return {
comment: adjustUrls(extractDescription(module)),
deprecated: extractDeprecated(module),
examples,
};
}
/**
* Processes all api methods of the given class. This does not include the constructor.
*
* @param module The module to process.
* @param accessor The code used to access the methods within the module.
* @returns A list containing the documentation for the api methods in the given module.
*/
export async function processModuleMethods(
module: DeclarationReflection,
accessor: string
): Promise<Method[]> {
return processMethods(selectApiMethodSignatures(module), accessor);
}
/**
* Processes all api methods.
*
* @param signatures The signatures to process.
* @param accessor The code used to access the methods.
* @returns A list containing the documentation for the api methods.
*/
export async function processMethods(
signatures: Record<string, SignatureReflection>,
accessor: string = ''
): Promise<Method[]> {
const methods: Method[] = [];
for (const [methodName, signature] of Object.entries(signatures)) {
console.debug(`- ${methodName}`);
methods.push(await analyzeSignature(signature, accessor, methodName));
}
return methods;
}
|
