forked from faker-js/faker
-
Notifications
You must be signed in to change notification settings - Fork 0
/
utils.ts
159 lines (141 loc) · 4.31 KB
/
utils.ts
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
import { resolve } from 'node:path';
import type { Options } from 'prettier';
import { format } from 'prettier';
import type {
CommentDisplayPart,
CommentTag,
SignatureReflection,
} from 'typedoc';
import * as TypeDoc from 'typedoc';
import prettierConfig from '../../.prettierrc.cjs';
import {
DefaultParameterAwareSerializer,
parameterDefaultReader,
patchProjectParameterDefaults,
} from './parameterDefaults';
export type Page = { text: string; link: string };
export type PageIndex = Array<Page>;
const pathRoot = resolve(__dirname, '..', '..');
export const pathDocsDir = resolve(pathRoot, 'docs');
export const pathOutputDir = resolve(pathDocsDir, 'api');
/**
* Creates and configures a new typedoc application.
*/
export function newTypeDocApp(): TypeDoc.Application {
const app = new TypeDoc.Application();
app.options.addReader(new TypeDoc.TSConfigReader());
// If you want TypeDoc to load typedoc.json files
//app.options.addReader(new TypeDoc.TypeDocReader());
// Read parameter defaults
app.converter.on(
TypeDoc.Converter.EVENT_CREATE_DECLARATION,
parameterDefaultReader
);
// Add to debug json output
app.serializer.addSerializer(new DefaultParameterAwareSerializer());
return app;
}
/**
* Apply our patches to the generated typedoc data.
*
* This is moved to a separate method to allow printing/saving the original content before patching it.
*
* @param project The project to patch.
*/
export function patchProject(project: TypeDoc.ProjectReflection): void {
patchProjectParameterDefaults(project);
}
/**
* Formats markdown contents.
*
* @param text The text to format.
*/
export function formatMarkdown(text: string): string {
return format(text, prettierMarkdown);
}
/**
* Formats typedoc contents.
*
* @param text The text to format.
*/
export function formatTypescript(text: string): string {
return format(text, prettierTypescript);
}
const prettierMarkdown: Options = {
...prettierConfig,
parser: 'markdown',
};
const prettierTypescript: Options = {
...prettierConfig,
parser: 'typescript',
};
/**
* Extracts the text (md) from a jsdoc tag.
*
* @param tag The tag to extract the text from.
* @param signature The signature to extract the text from.
*/
export function extractTagContent(
tag: `@${string}`,
signature?: SignatureReflection,
tagProcessor: (tag: CommentTag) => string[] = joinTagContent
): string[] {
return signature?.comment?.getTags(tag).flatMap(tagProcessor) ?? [];
}
/**
* Extracts the examples from the jsdocs without the surrounding md code block.
*
* @param signature The signature to extract the examples from.
*/
export function extractRawExamples(signature?: SignatureReflection): string[] {
return extractTagContent('@example', signature).map((tag) =>
tag.replace(/^```ts\n/, '').replace(/\n```$/, '')
);
}
/**
* Extracts all the `@see` references from the jsdocs separately.
*
* @param signature The signature to extract the see also references from.
*/
export function extractSeeAlsos(signature?: SignatureReflection): string[] {
return extractTagContent('@see', signature, (tag) => {
const content = tag.content;
if (content.length === 1) {
return joinTagContent(tag);
}
return tag.content
.filter((_, index) => index % 3 === 1) // ['-', 'content', '\n']
.map((part) => part.text);
});
}
/**
* Joins the parts of the given jsdocs tag.
*/
export function joinTagContent(tag: CommentTag): string[] {
return [joinTagParts(tag?.content)];
}
export function joinTagParts(parts: CommentDisplayPart[]): string;
export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined;
export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined {
return parts?.map((part) => part.text).join('');
}
/**
* Checks if the given signature is deprecated.
*
* @param signature The signature to check.
*
* @returns `true` if it is deprecated, otherwise `false`.
*/
export function isDeprecated(signature: SignatureReflection): boolean {
return extractTagContent('@deprecated', signature).length > 0;
}
/**
* Extracts the "since" tag from the provided signature.
*
* @param signature The signature to check.
*
* @returns the contents of the @since tag
*/
export function since(signature: SignatureReflection): string {
return extractTagContent('@since', signature).join().trim();
}