Skip to content

Commit dcb0bd6

Browse files
Gerrit0Gerrit0
committed
Introduce Context.createSymbolId
Ref: Gerrit0/typedoc-plugin-missing-exports#34
1 parent c84da4f commit dcb0bd6

File tree

10 files changed

+120
-141
lines changed

10 files changed

+120
-141
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ title: Changelog
88

99
- If using JS config files, the `plugin` function can now be given plugin functions to load.
1010
- Permit `-` within tag names to support `typescript-json-schema`'s `@TJS-type` tag, #2972.
11+
- Exposed `Context.createSymbolId` for use by plugins.
1112

1213
### Thanks!
1314

‎src/lib/converter/comments/blockLexer.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
import ts from "typescript";
22
import { type Token, TokenSyntaxKind } from "./lexer.js";
33
import { resolveAliasedSymbol } from "../utils/symbols.js";
4-
import { createSymbolId } from "../factories/symbol-id.js";
4+
import type { Context } from "../context.js";
55

66
export function* lexBlockComment(
77
file: string,
88
pos = 0,
99
end = file.length,
10+
createSymbolId: Context["createSymbolId"] = () => {
11+
throw new Error("unreachable");
12+
},
1013
jsDoc: ts.JSDoc | undefined = undefined,
1114
checker: ts.TypeChecker | undefined = undefined,
1215
): Generator<Token, undefined, undefined> {
@@ -19,6 +22,7 @@ export function* lexBlockComment(
1922
end,
2023
getLinkTags(jsDoc),
2124
checker,
25+
createSymbolId,
2226
)
2327
) {
2428
if (token.kind === TokenSyntaxKind.Text) {
@@ -82,6 +86,7 @@ function* lexBlockComment2(
8286
ts.JSDocLink | ts.JSDocLinkCode | ts.JSDocLinkPlain
8387
>,
8488
checker: ts.TypeChecker | undefined,
89+
createSymbolId: Context["createSymbolId"],
8590
): Generator<Token, undefined, undefined> {
8691
pos += 2; // Leading '/*'
8792
end -= 2; // Trailing '*/'

‎src/lib/converter/comments/index.ts‎

Lines changed: 51 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import { lexLineComments } from "./lineLexer.js";
1313
import { parseComment } from "./parser.js";
1414
import type { FileRegistry } from "../../models/FileRegistry.js";
1515
import { assertNever, i18n, type Logger } from "#utils";
16+
import type { Context } from "../context.js";
1617

1718
export interface CommentParserConfig {
1819
blockTags: Set<string>;
@@ -24,6 +25,22 @@ export interface CommentParserConfig {
2425
commentStyle: CommentStyle;
2526
}
2627

28+
export interface CommentContext {
29+
config: CommentParserConfig;
30+
logger: Logger;
31+
checker: ts.TypeChecker;
32+
files: FileRegistry;
33+
createSymbolId: Context["createSymbolId"];
34+
}
35+
36+
export interface CommentContextOptionalChecker {
37+
config: CommentParserConfig;
38+
logger: Logger;
39+
checker?: ts.TypeChecker | undefined;
40+
files: FileRegistry;
41+
createSymbolId: Context["createSymbolId"];
42+
}
43+
2744
const jsDocCommentKinds = [
2845
ts.SyntaxKind.JSDocPropertyTag,
2946
ts.SyntaxKind.JSDocCallbackTag,
@@ -45,10 +62,7 @@ export function clearCommentCache() {
4562

4663
function getCommentWithCache(
4764
discovered: DiscoveredComment | undefined,
48-
config: CommentParserConfig,
49-
logger: Logger,
50-
checker: ts.TypeChecker | undefined,
51-
files: FileRegistry,
65+
context: CommentContextOptionalChecker,
5266
) {
5367
if (!discovered) return;
5468

@@ -68,22 +82,19 @@ function getCommentWithCache(
6882
file.text,
6983
ranges[0].pos,
7084
ranges[0].end,
85+
context.createSymbolId,
7186
jsDoc,
72-
checker,
87+
context.checker,
7388
),
74-
config,
7589
file,
76-
logger,
77-
files,
90+
context,
7891
);
7992
break;
8093
case ts.SyntaxKind.SingleLineCommentTrivia:
8194
comment = parseComment(
8295
lexLineComments(file.text, ranges),
83-
config,
8496
file,
85-
logger,
86-
files,
97+
context,
8798
);
8899
break;
89100
default:
@@ -100,18 +111,15 @@ function getCommentWithCache(
100111

101112
function getCommentImpl(
102113
commentSource: DiscoveredComment | undefined,
103-
config: CommentParserConfig,
104-
logger: Logger,
105114
moduleComment: boolean,
106-
checker: ts.TypeChecker | undefined,
107-
files: FileRegistry,
115+
context: CommentContext,
108116
) {
109117
const comment = getCommentWithCache(
110118
commentSource,
111-
config,
112-
logger,
113-
config.useTsLinkResolution ? checker : undefined,
114-
files,
119+
{
120+
...context,
121+
checker: context.config.useTsLinkResolution ? context.checker : undefined,
122+
},
115123
);
116124

117125
if (comment?.getTag("@import") || comment?.getTag("@license")) {
@@ -145,10 +153,7 @@ function getCommentImpl(
145153
export function getComment(
146154
symbol: ts.Symbol,
147155
kind: ReflectionKind,
148-
config: CommentParserConfig,
149-
logger: Logger,
150-
checker: ts.TypeChecker,
151-
files: FileRegistry,
156+
context: CommentContext,
152157
): Comment | undefined {
153158
const declarations = symbol.declarations || [];
154159

@@ -158,16 +163,13 @@ export function getComment(
158163
) {
159164
return getJsDocComment(
160165
declarations[0] as ts.JSDocPropertyLikeTag,
161-
config,
162-
logger,
163-
checker,
164-
files,
166+
context,
165167
);
166168
}
167169

168170
const sf = declarations.find(ts.isSourceFile);
169171
if (sf) {
170-
return getFileComment(sf, config, logger, checker, files);
172+
return getFileComment(sf, context);
171173
}
172174

173175
const isModule = declarations.some((decl) => {
@@ -181,25 +183,19 @@ export function getComment(
181183
discoverComment(
182184
symbol,
183185
kind,
184-
logger,
185-
config.commentStyle,
186-
checker,
187-
!config.suppressCommentWarningsInDeclarationFiles,
186+
context.logger,
187+
context.config.commentStyle,
188+
context.checker,
189+
!context.config.suppressCommentWarningsInDeclarationFiles,
188190
),
189-
config,
190-
logger,
191191
isModule,
192-
checker,
193-
files,
192+
context,
194193
);
195194

196195
if (!comment && kind === ReflectionKind.Property) {
197196
return getConstructorParamPropertyComment(
198197
symbol,
199-
config,
200-
logger,
201-
checker,
202-
files,
198+
context,
203199
);
204200
}
205201

@@ -209,40 +205,28 @@ export function getComment(
209205
export function getNodeComment(
210206
node: ts.Node,
211207
moduleComment: boolean,
212-
config: CommentParserConfig,
213-
logger: Logger,
214-
checker: ts.TypeChecker | undefined,
215-
files: FileRegistry,
208+
context: CommentContext,
216209
) {
217210
return getCommentImpl(
218-
discoverNodeComment(node, config.commentStyle),
219-
config,
220-
logger,
211+
discoverNodeComment(node, context.config.commentStyle),
221212
moduleComment,
222-
checker,
223-
files,
213+
context,
224214
);
225215
}
226216

227217
export function getFileComment(
228218
file: ts.SourceFile,
229-
config: CommentParserConfig,
230-
logger: Logger,
231-
checker: ts.TypeChecker | undefined,
232-
files: FileRegistry,
219+
context: CommentContext,
233220
): Comment | undefined {
234221
for (
235222
const commentSource of discoverFileComments(
236223
file,
237-
config.commentStyle,
224+
context.config.commentStyle,
238225
)
239226
) {
240227
const comment = getCommentWithCache(
241228
commentSource,
242-
config,
243-
logger,
244-
config.useTsLinkResolution ? checker : undefined,
245-
files,
229+
context,
246230
);
247231

248232
if (comment?.getTag("@license") || comment?.getTag("@import")) {
@@ -261,16 +245,13 @@ export function getFileComment(
261245

262246
function getConstructorParamPropertyComment(
263247
symbol: ts.Symbol,
264-
config: CommentParserConfig,
265-
logger: Logger,
266-
checker: ts.TypeChecker,
267-
files: FileRegistry,
248+
context: CommentContext,
268249
): Comment | undefined {
269250
const decl = symbol.declarations?.find(ts.isParameter);
270251
if (!decl) return;
271252

272253
const ctor = decl.parent;
273-
const comment = getSignatureComment(ctor, config, logger, checker, files);
254+
const comment = getSignatureComment(ctor, context);
274255

275256
const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
276257
if (paramTag) {
@@ -282,18 +263,12 @@ function getConstructorParamPropertyComment(
282263

283264
export function getSignatureComment(
284265
declaration: ts.SignatureDeclaration | ts.JSDocSignature,
285-
config: CommentParserConfig,
286-
logger: Logger,
287-
checker: ts.TypeChecker,
288-
files: FileRegistry,
266+
context: CommentContext,
289267
): Comment | undefined {
290268
return getCommentImpl(
291-
discoverSignatureComment(declaration, checker, config.commentStyle),
292-
config,
293-
logger,
269+
discoverSignatureComment(declaration, context.checker, context.config.commentStyle),
294270
false,
295-
checker,
296-
files,
271+
context,
297272
);
298273
}
299274

@@ -304,10 +279,7 @@ export function getJsDocComment(
304279
| ts.JSDocTypedefTag
305280
| ts.JSDocTemplateTag
306281
| ts.JSDocEnumTag,
307-
config: CommentParserConfig,
308-
logger: Logger,
309-
checker: ts.TypeChecker | undefined,
310-
files: FileRegistry,
282+
context: CommentContext,
311283
): Comment | undefined {
312284
const file = declaration.getSourceFile();
313285

@@ -331,10 +303,7 @@ export function getJsDocComment(
331303
jsDoc: parent,
332304
inheritedFromParentDeclaration: false,
333305
},
334-
config,
335-
logger,
336-
config.useTsLinkResolution ? checker : undefined,
337-
files,
306+
context,
338307
)!;
339308

340309
// And pull out the tag we actually care about.
@@ -352,7 +321,7 @@ export function getJsDocComment(
352321
// We could just put the same comment on everything, but due to how comment parsing works,
353322
// we'd have to search for any @template with a name starting with the first type parameter's name
354323
// which feels horribly hacky.
355-
logger.warn(
324+
context.logger.warn(
356325
i18n.multiple_type_parameters_on_template_tag_unsupported(),
357326
declaration,
358327
);
@@ -378,7 +347,7 @@ export function getJsDocComment(
378347
// was a comment attached. If there wasn't, then don't error about failing to find
379348
// a tag because this is unsupported.
380349
if (!ts.isJSDocTemplateTag(declaration)) {
381-
logger.error(
350+
context.logger.error(
382351
i18n.failed_to_find_jsdoc_tag_for_name_0(name),
383352
declaration,
384353
);

‎src/lib/converter/comments/parser.ts‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import assert, { ok } from "assert";
22
import { parseDocument as parseYamlDoc } from "yaml";
3-
import type { CommentParserConfig } from "./index.js";
3+
import type { CommentContextOptionalChecker, CommentParserConfig } from "./index.js";
44
import { Comment, type CommentDisplayPart, CommentTag, type InlineTagDisplayPart } from "../../models/index.js";
55
import type { MinimalSourceFile } from "#utils";
66
import { nicePath } from "../../utils/paths.js";
@@ -62,10 +62,8 @@ function makeLookaheadGenerator<T>(
6262

6363
export function parseComment(
6464
tokens: Generator<Token, undefined, undefined>,
65-
config: CommentParserConfig,
6665
file: MinimalSourceFile,
67-
logger: Logger,
68-
files: FileRegistry,
66+
context: CommentContextOptionalChecker,
6967
): Comment {
7068
const lexer = makeLookaheadGenerator(tokens);
7169
const tok = lexer.done() || lexer.peek();
@@ -75,15 +73,15 @@ export function parseComment(
7573
comment.summary = blockContent(
7674
comment,
7775
lexer,
78-
config,
76+
context.config,
7977
i18n,
8078
warningImpl,
81-
files,
79+
context.files,
8280
);
8381

8482
while (!lexer.done()) {
8583
comment.blockTags.push(
86-
blockTag(comment, lexer, config, i18n, warningImpl, files),
84+
blockTag(comment, lexer, context.config, i18n, warningImpl, context.files),
8785
);
8886
}
8987

@@ -93,19 +91,19 @@ export function parseComment(
9391
comment,
9492
i18n,
9593
() => `${nicePath(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`,
96-
(message) => logger.warn(message),
94+
(message) => context.logger.warn(message),
9795
);
9896

9997
return comment;
10098

10199
function warningImpl(message: TranslatedString, token: Token) {
102100
if (
103-
config.suppressCommentWarningsInDeclarationFiles &&
101+
context.config.suppressCommentWarningsInDeclarationFiles &&
104102
hasDeclarationFileExtension(file.fileName)
105103
) {
106104
return;
107105
}
108-
logger.warn(message, token.pos, file);
106+
context.logger.warn(message, token.pos, file);
109107
}
110108
}
111109

0 commit comments

Comments
 (0)