diff --git a/CHANGELOG.md b/CHANGELOG.md index fa1e9051c..667933a59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ - Header anchor links in rendered markdown are now more consistent with headers generated by TypeDoc, #2546. - Types rendered in the `Returns` header are now properly colored, #2546. - Links added with the `navigationLinks` option are now moved into the pull out navigation on mobile displays, #2548. +- `@license` and `@import` comments will be ignored at the top of files, #2552. ### Thanks! diff --git a/scripts/testcase.js b/scripts/testcase.js index b531d9529..8b53bda68 100644 --- a/scripts/testcase.js +++ b/scripts/testcase.js @@ -37,8 +37,8 @@ function guessExtension(code) { } async function main() { - if (process.argv.length !== 3) { - console.log("Usage: node scripts/testcase.js "); + if (process.argv.length !== 3 && process.argv.length !== 4) { + console.log("Usage: node scripts/testcase.js [lang]"); process.exit(1); } @@ -62,7 +62,8 @@ async function main() { return; } - const file = `src/test/converter2/issues/gh${issue}${guessExtension(code)}`; + const ext = process.argv[3] ? `.${process.argv[3]}` : guessExtension(code); + const file = `src/test/converter2/issues/gh${issue}${ext}`; await writeFile(file, code.text); await exec(`code ${file} src/test/issues.c2.test.ts`); } diff --git a/src/lib/converter/comments/discovery.ts b/src/lib/converter/comments/discovery.ts index 2a15f4a99..27c50b108 100644 --- a/src/lib/converter/comments/discovery.ts +++ b/src/lib/converter/comments/discovery.ts @@ -110,7 +110,7 @@ export interface DiscoveredComment { jsDoc: ts.JSDoc | undefined; } -export function discoverFileComment( +export function discoverFileComments( node: ts.SourceFile, commentStyle: CommentStyle, ) { @@ -120,17 +120,17 @@ export function discoverFileComment( ts.getLeadingCommentRanges(text, node.pos), ); - const selectedDocComment = comments.find((ranges) => + const selectedDocComments = comments.filter((ranges) => permittedRange(text, ranges, commentStyle), ); - if (selectedDocComment) { + return selectedDocComments.map((ranges) => { return { file: node, - ranges: selectedDocComment, - jsDoc: findJsDocForComment(node, selectedDocComment), + ranges, + jsDoc: findJsDocForComment(node, ranges), }; - } + }); } export function discoverNodeComment( diff --git a/src/lib/converter/comments/index.ts b/src/lib/converter/comments/index.ts index da7b776db..c233c07a7 100644 --- a/src/lib/converter/comments/index.ts +++ b/src/lib/converter/comments/index.ts @@ -9,7 +9,7 @@ import { lexBlockComment } from "./blockLexer"; import { DiscoveredComment, discoverComment, - discoverFileComment, + discoverFileComments, discoverNodeComment, discoverSignatureComment, } from "./discovery"; @@ -143,8 +143,12 @@ export function getComment( ); } + const sf = declarations.find(ts.isSourceFile); + if (sf) { + return getFileComment(sf, config, logger, commentStyle, checker); + } + const isModule = declarations.some((decl) => { - if (ts.isSourceFile(decl)) return true; if (ts.isModuleDeclaration(decl) && ts.isStringLiteral(decl.name)) { return true; } @@ -196,13 +200,26 @@ export function getFileComment( commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, ): Comment | undefined { - return getCommentImpl( - discoverFileComment(file, commentStyle), - config, - logger, - /* moduleComment */ true, - checker, - ); + for (const commentSource of discoverFileComments(file, commentStyle)) { + const comment = getCommentWithCache( + commentSource, + config, + logger, + checker, + ); + + if (comment?.getTag("@license") || comment?.getTag("@import")) { + continue; + } + + if ( + comment?.getTag("@module") || + comment?.hasModifier("@packageDocumentation") + ) { + return comment; + } + return; + } } function getConstructorParamPropertyComment( diff --git a/src/lib/utils/options/tsdoc-defaults.ts b/src/lib/utils/options/tsdoc-defaults.ts index 9ae30e874..c09ba21cf 100644 --- a/src/lib/utils/options/tsdoc-defaults.ts +++ b/src/lib/utils/options/tsdoc-defaults.ts @@ -28,6 +28,8 @@ export const blockTags = [ "@prop", "@property", "@satisfies", + "@license", + "@import", ] as const; export const tsdocInlineTags = ["@link", "@inheritDoc", "@label"] as const; diff --git a/src/test/converter2/issues/gh2552.js b/src/test/converter2/issues/gh2552.js new file mode 100644 index 000000000..18af18ab5 --- /dev/null +++ b/src/test/converter2/issues/gh2552.js @@ -0,0 +1,16 @@ +/** + * Summary + * @license MIT + * + * Full permission notice. + */ + +// TS 5.5 @import comments +/** @import * as ts from "typescript" */ + +/** + * This is an awesome module. + * @module good-module + */ + +export function goodFunction() {} diff --git a/src/test/issues.c2.test.ts b/src/test/issues.c2.test.ts index 7c2c69425..033067d1e 100644 --- a/src/test/issues.c2.test.ts +++ b/src/test/issues.c2.test.ts @@ -1430,4 +1430,12 @@ describe("Issue Tests", () => { equal(cb2.type?.type, "reflection"); equal(cb2.type.declaration.signatures![0].comment, undefined); }); + + it("Ignores @license and @import comments at the top of the file, #2552", () => { + const project = convert(); + equal( + Comment.combineDisplayParts(project.comment?.summary), + "This is an awesome module.", + ); + }); }); diff --git a/tsdoc.json b/tsdoc.json index 5e5590ec3..977281fbe 100644 --- a/tsdoc.json +++ b/tsdoc.json @@ -1,5 +1,6 @@ { "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + // If updating this, also update tsdoc-defaults.ts "noStandardTags": false, "tagDefinitions": [ { @@ -93,6 +94,14 @@ "tagName": "@satisfies", "syntaxKind": "block" }, + { + "tagName": "@license", + "syntaxKind": "block" + }, + { + "tagName": "@import", + "syntaxKind": "block" + }, { "tagName": "@overload", "syntaxKind": "modifier"