diff --git a/CHANGELOG.md b/CHANGELOG.md index 72e79183a..5f472f609 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Unreleased +### Features + +- Added support for discovering a "module" comment on global files, #2165. + ### Bug Fixes - Even more contrast fixes, #2248. diff --git a/src/lib/converter/comments/discovery.ts b/src/lib/converter/comments/discovery.ts index 51a4079f1..20a753125 100644 --- a/src/lib/converter/comments/discovery.ts +++ b/src/lib/converter/comments/discovery.ts @@ -101,6 +101,29 @@ export interface DiscoveredComment { jsDoc: ts.JSDoc | undefined; } +export function discoverFileComment( + node: ts.SourceFile, + commentStyle: CommentStyle +) { + const text = node.text; + + const comments = collectCommentRanges( + ts.getLeadingCommentRanges(text, node.pos) + ); + + const selectedDocComment = comments.find((ranges) => + permittedRange(text, ranges, commentStyle) + ); + + if (selectedDocComment) { + return { + file: node, + ranges: selectedDocComment, + jsDoc: findJsDocForComment(node, selectedDocComment), + }; + } +} + export function discoverComment( symbol: ts.Symbol, kind: ReflectionKind, diff --git a/src/lib/converter/comments/index.ts b/src/lib/converter/comments/index.ts index 5d8e3d518..551390aa1 100644 --- a/src/lib/converter/comments/index.ts +++ b/src/lib/converter/comments/index.ts @@ -9,6 +9,7 @@ import { lexBlockComment } from "./blockLexer"; import { DiscoveredComment, discoverComment, + discoverFileComment, discoverSignatureComment, } from "./discovery"; import { lexLineComments } from "./lineLexer"; @@ -162,6 +163,22 @@ export function getComment( return comment; } +export function getFileComment( + file: ts.SourceFile, + config: CommentParserConfig, + logger: Logger, + commentStyle: CommentStyle, + checker: ts.TypeChecker | undefined +): Comment | undefined { + return getCommentImpl( + discoverFileComment(file, commentStyle), + config, + logger, + /* moduleComment */ true, + checker + ); +} + function getConstructorParamPropertyComment( symbol: ts.Symbol, config: CommentParserConfig, diff --git a/src/lib/converter/context.ts b/src/lib/converter/context.ts index 3616084f4..617546c07 100644 --- a/src/lib/converter/context.ts +++ b/src/lib/converter/context.ts @@ -14,7 +14,12 @@ import type { Converter } from "./converter"; import { isNamedNode } from "./utils/nodes"; import { ConverterEvents } from "./converter-events"; import { resolveAliasedSymbol } from "./utils/symbols"; -import { getComment, getJsDocComment, getSignatureComment } from "./comments"; +import { + getComment, + getFileComment, + getJsDocComment, + getSignatureComment, +} from "./comments"; import { getHumanName } from "../utils/tsutils"; /** @@ -265,6 +270,16 @@ export class Context { ); } + getFileComment(node: ts.SourceFile) { + return getFileComment( + node, + this.converter.config, + this.logger, + this.converter.commentStyle, + this.converter.useTsLinkResolution ? this.checker : undefined + ); + } + getJsDocComment( declaration: | ts.JSDocPropertyLikeTag diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts index 8a4dab1ad..236f117bc 100644 --- a/src/lib/converter/converter.ts +++ b/src/lib/converter/converter.ts @@ -368,8 +368,9 @@ export class Converter extends ChildableComponent< // Special case for when we're giving a single entry point, we don't need to // create modules for each entry. Register the project as this module. context.project.registerReflection(context.project, symbol); - context.project.comment = - symbol && context.getComment(symbol, context.project.kind); + context.project.comment = symbol + ? context.getComment(symbol, context.project.kind) + : context.getFileComment(node); context.trigger( Converter.EVENT_CREATE_DECLARATION, context.project @@ -383,6 +384,10 @@ export class Converter extends ChildableComponent< entryName ); + if (!reflection.comment && !symbol) { + reflection.comment = context.getFileComment(node); + } + if (entryPoint.readmeFile) { const readme = readFile(entryPoint.readmeFile); const comment = this.parseRawComment( diff --git a/src/test/converter2/issues/gh2165.ts b/src/test/converter2/issues/gh2165.ts new file mode 100644 index 000000000..9729b1b9e --- /dev/null +++ b/src/test/converter2/issues/gh2165.ts @@ -0,0 +1,6 @@ +/** + * 'module' comment + * @module + */ + +var globalFile = true; diff --git a/src/test/issues.c2.test.ts b/src/test/issues.c2.test.ts index e52832bef..2ad61274e 100644 --- a/src/test/issues.c2.test.ts +++ b/src/test/issues.c2.test.ts @@ -1008,6 +1008,14 @@ describe("Issue Tests", () => { ); }); + it("#2165 module comments on global files", () => { + const project = convert(); + equal( + Comment.combineDisplayParts(project.comment?.summary), + "'module' comment" + ); + }); + it("#2175", () => { const project = convert(); const def = query(project, "default");