Ignore @license and @import comments at the top of files

Resolves #2552

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!
 

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 <issue number>");
+    if (process.argv.length !== 3 && process.argv.length !== 4) {
+        console.log("Usage: node scripts/testcase.js <issue number> [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`);
 }

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(

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(

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;

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() {}

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.",
+        );
+    });
 });

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"