typedoc 0.28.14 → 0.28.16

package/dist/lib/cli.js

@@ -75,7 +75,8 @@ async function run(app) {
     }
     const preValidationWarnCount = app.logger.warningCount;
     app.validate(project);
-    const hadValidationWarnings = app.logger.warningCount !== preValidationWarnCount;
+    const hadValidationWarnings = app.logger.warningCount !== preValidationWarnCount ||
+        app.logger.validationWarningCount != 0;
     if (app.logger.hasErrors()) {
         return ExitCodes.ValidationError;
     }

package/dist/lib/converter/comments/index.d.ts

@@ -1,8 +1,8 @@
 import ts from "typescript";
 import { Comment, ReflectionKind } from "../../models/index.js";
-import type { CommentStyle, JsDocCompatibility } from "../../utils/options/declaration.js";
+import type { CommentStyle, JsDocCompatibility, ValidationOptions } from "../../utils/options/declaration.js";
 import type { FileRegistry } from "../../models/FileRegistry.js";
-import { type Logger } from "#utils";
+import { Logger } from "#utils";
 import type { Context } from "../context.js";
 export interface CommentParserConfig {
     blockTags: Set<string>;
@@ -13,6 +13,7 @@ export interface CommentParserConfig {
     suppressCommentWarningsInDeclarationFiles: boolean;
     useTsLinkResolution: boolean;
     commentStyle: CommentStyle;
+    validationOptions: ValidationOptions;
 }
 export interface CommentContext {
     config: CommentParserConfig;

package/dist/lib/converter/comments/index.js

@@ -4,7 +4,7 @@ import { lexBlockComment } from "./blockLexer.js";
 import { discoverComment, discoverFileComments, discoverNodeComment, discoverSignatureComment, } from "./discovery.js";
 import { lexLineComments } from "./lineLexer.js";
 import { parseComment } from "./parser.js";
-import { assertNever, i18n } from "#utils";
+import { assertNever, i18n, Logger, setUnion } from "#utils";
 const jsDocCommentKinds = [
     ts.SyntaxKind.JSDocPropertyTag,
     ts.SyntaxKind.JSDocCallbackTag,
@@ -21,16 +21,10 @@ export function clearCommentCache() {
     commentCache = new WeakMap();
     commentDiscoveryId = 0;
 }
-function getCommentWithCache(discovered, context) {
+function getCommentIgnoringCacheNoDiscoveryId(discovered, context) {
     if (!discovered)
         return;
     const { file, ranges, jsDoc } = discovered;
-    const cache = commentCache.get(file) || new Map();
-    if (cache.has(ranges[0].pos)) {
-        const clone = cache.get(ranges[0].pos).clone();
-        clone.inheritedFromParentDeclaration = discovered.inheritedFromParentDeclaration;
-        return clone;
-    }
     let comment;
     switch (ranges[0].kind) {
         case ts.SyntaxKind.MultiLineCommentTrivia:
@@ -42,8 +36,23 @@ function getCommentWithCache(discovered, context) {
         default:
             assertNever(ranges[0].kind);
     }
-    comment.discoveryId = ++commentDiscoveryId;
     comment.inheritedFromParentDeclaration = discovered.inheritedFromParentDeclaration;
+    return comment;
+}
+function getCommentWithCache(discovered, context) {
+    if (!discovered)
+        return;
+    const { file, ranges } = discovered;
+    const cache = commentCache.get(file) || new Map();
+    if (cache.has(ranges[0].pos)) {
+        const clone = cache.get(ranges[0].pos).clone();
+        clone.inheritedFromParentDeclaration = discovered.inheritedFromParentDeclaration;
+        return clone;
+    }
+    const comment = getCommentIgnoringCacheNoDiscoveryId(discovered, context);
+    if (!comment)
+        return;
+    comment.discoveryId = ++commentDiscoveryId;
     cache.set(ranges[0].pos, comment);
     commentCache.set(file, cache);
     return comment.clone();
@@ -99,14 +108,24 @@ export function getNodeComment(node, moduleComment, context) {
     return getCommentImpl(discoverNodeComment(node, context.config.commentStyle), moduleComment, context);
 }
 export function getFileComment(file, context) {
+    const quietContext = {
+        ...context,
+        logger: new Logger(),
+    };
     for (const commentSource of discoverFileComments(file, context.config.commentStyle)) {
-        const comment = getCommentWithCache(commentSource, context);
+        // First parse the comment without adding the parse to the cache
+        // and without logging any messages. If we end up not using this as
+        // a file comment we want to avoid parsing it with warnings here as
+        // it might be associated with a JSDoc parse which has special
+        // handling to allow modifier tags to be specified as {@mod}
+        // and if it gets added to the cache here we'll get unwanted warnings
+        const comment = getCommentIgnoringCacheNoDiscoveryId(commentSource, quietContext);
         if (comment?.getTag("@license") || comment?.getTag("@import")) {
             continue;
         }
         if (comment?.getTag("@module") ||
             comment?.hasModifier("@packageDocumentation")) {
-            return comment;
+            return getCommentWithCache(commentSource, context);
         }
         return;
     }
@@ -127,6 +146,33 @@ function getConstructorParamPropertyComment(symbol, context) {
 export function getSignatureComment(declaration, context) {
     return getCommentImpl(discoverSignatureComment(declaration, context.checker, context.config.commentStyle), false, context);
 }
+function buildJsDocCommentFromParts(declaration, parts, sourceComment, context) {
+    if (!parts) {
+        return undefined;
+    }
+    const comment = new Comment(Comment.cloneDisplayParts(parts));
+    comment.sourcePath = sourceComment.sourcePath;
+    for (let i = 0; i < comment.summary.length;) {
+        const part = comment.summary[i];
+        if (part.kind === "inline-tag" &&
+            !part.text.trim() &&
+            context.config.modifierTags.has(part.tag)) {
+            comment.modifierTags.add(part.tag);
+            comment.summary.splice(i, 1);
+        }
+        else if (part.kind === "inline-tag" &&
+            part.text.trim() &&
+            context.config.modifierTags.has(part.tag) &&
+            !context.config.inlineTags.has(part.tag)) {
+            context.logger.warn(i18n.inline_tag_0_not_parsed_as_modifier_tag_1(part.tag, part.text.trim()), declaration);
+            ++i;
+        }
+        else {
+            ++i;
+        }
+    }
+    return comment;
+}
 export function getJsDocComment(declaration, context) {
     const file = declaration.getSourceFile();
     // First, get the whole comment. We know we'll need all of it.
@@ -134,6 +180,15 @@ export function getJsDocComment(declaration, context) {
     while (!ts.isJSDoc(parent)) {
         parent = parent.parent;
     }
+    // Build a custom context to allow modifier tags to be written as inline
+    // tags as otherwise there's no way to specify them here #2916 #3050
+    const contextWithInline = {
+        ...context,
+        config: {
+            ...context.config,
+            inlineTags: setUnion(context.config.inlineTags, context.config.modifierTags),
+        },
+    };
     // Then parse it.
     const comment = getCommentWithCache({
         file,
@@ -146,12 +201,10 @@ export function getJsDocComment(declaration, context) {
         ],
         jsDoc: parent,
         inheritedFromParentDeclaration: false,
-    }, context);
+    }, contextWithInline);
     // And pull out the tag we actually care about.
     if (ts.isJSDocEnumTag(declaration)) {
-        const result = new Comment(comment.getTag("@enum")?.content);
-        result.sourcePath = comment.sourcePath;
-        return result;
+        return buildJsDocCommentFromParts(declaration, comment.getTag("@enum")?.content, comment, context);
     }
     if (ts.isJSDocTemplateTag(declaration) &&
         declaration.comment &&
@@ -183,8 +236,6 @@ export function getJsDocComment(declaration, context) {
         }
     }
     else {
-        const result = new Comment(Comment.cloneDisplayParts(tag.content));
-        result.sourcePath = comment.sourcePath;
-        return result;
+        return buildJsDocCommentFromParts(declaration, tag.content, comment, context);
     }
 }

package/dist/lib/converter/comments/parser.js

@@ -45,12 +45,12 @@ export function parseComment(tokens, file, context) {
     const tok = lexer.done() || lexer.peek();
     const comment = new Comment();
     comment.sourcePath = file.fileName;
-    comment.summary = blockContent(comment, lexer, context.config, i18n, warningImpl, context.files);
+    comment.summary = blockContent(comment, lexer, context.config, warningImpl, validationWarningImpl, context.files);
     while (!lexer.done()) {
-        comment.blockTags.push(blockTag(comment, lexer, context.config, i18n, warningImpl, context.files));
+        comment.blockTags.push(blockTag(comment, lexer, context.config, warningImpl, validationWarningImpl, context.files));
     }
     const tok2 = tok;
-    postProcessComment(comment, i18n, () => `${nicePath(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`, (message) => context.logger.warn(message));
+    postProcessComment(comment, () => `${nicePath(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`, (message) => context.logger.warn(message));
     return comment;
     function warningImpl(message, token) {
         if (context.config.suppressCommentWarningsInDeclarationFiles &&
@@ -59,6 +59,13 @@ export function parseComment(tokens, file, context) {
         }
         context.logger.warn(message, token.pos, file);
     }
+    function validationWarningImpl(message, token) {
+        if (context.config.suppressCommentWarningsInDeclarationFiles &&
+            hasDeclarationFileExtension(file.fileName)) {
+            return;
+        }
+        context.logger.validationWarning(message, token.pos, file);
+    }
 }
 /**
  * Intended for parsing markdown documents. This only parses code blocks and
@@ -95,13 +102,22 @@ export function parseCommentString(tokens, config, file, logger, files) {
             case TokenSyntaxKind.Text:
             case TokenSyntaxKind.Tag:
             case TokenSyntaxKind.CloseBrace:
-                textContent(file.fileName, next, i18n, (msg, token) => logger.warn(msg, token.pos, file), content, files, atNewLine, reentry);
+                textContent({
+                    sourcePath: file.fileName,
+                    token: next,
+                    warning: (msg, token) => logger.warn(msg, token.pos, file),
+                    validationWarning: (msg, token) => logger.validationWarning(msg, token.pos, file),
+                    files,
+                    atNewLine,
+                    validationOptions: config.validationOptions,
+                }, 
+                /* out */ content, reentry);
                 break;
             case TokenSyntaxKind.Code:
                 content.push({ kind: "code", text: next.text });
                 break;
             case TokenSyntaxKind.OpenBrace:
-                inlineTag(lexer, content, suppressWarningsConfig, i18n, (message, token) => logger.warn(message, token.pos, file));
+                inlineTag(lexer, content, suppressWarningsConfig, (message, token) => logger.warn(message, token.pos, file));
                 consume = false;
                 break;
             default:
@@ -161,7 +177,7 @@ function makeCodeBlock(text) {
  * Loop over comment, produce lint warnings, and set tag names for tags
  * which have them.
  */
-function postProcessComment(comment, i18n, getPosition, warning) {
+function postProcessComment(comment, getPosition, warning) {
     for (const tag of comment.blockTags) {
         if (HAS_USER_IDENTIFIER.includes(tag.tag) && tag.content.length) {
             const first = tag.content[0];
@@ -211,7 +227,7 @@ function postProcessComment(comment, i18n, getPosition, warning) {
     }
 }
 const aliasedTags = new Map([["@return", "@returns"]]);
-function blockTag(comment, lexer, config, i18n, warning, files) {
+function blockTag(comment, lexer, config, warning, validationWarning, files) {
     const blockTag = lexer.take();
     ok(blockTag.kind === TokenSyntaxKind.Tag, "blockTag called not at the start of a block tag."); // blockContent is broken if this fails.
     if (!config.blockTags.has(blockTag.text)) {
@@ -220,7 +236,7 @@ function blockTag(comment, lexer, config, i18n, warning, files) {
     const tagName = aliasedTags.get(blockTag.text) || blockTag.text;
     let content;
     if (tagName === "@example") {
-        return exampleBlock(comment, lexer, config, i18n, warning, files);
+        return exampleBlock(comment, lexer, config, warning, validationWarning, files);
     }
     let typeAnnotation;
     if (!lexer.done() &&
@@ -234,10 +250,10 @@ function blockTag(comment, lexer, config, i18n, warning, files) {
     }
     if (["@default", "@defaultValue"].includes(tagName) &&
         config.jsDocCompatibility.defaultTag) {
-        content = defaultBlockContent(comment, lexer, config, i18n, warning, files);
+        content = defaultBlockContent(comment, lexer, config, warning, validationWarning, files);
     }
     else {
-        content = blockContent(comment, lexer, config, i18n, warning, files);
+        content = blockContent(comment, lexer, config, warning, validationWarning, files);
     }
     const tag = new CommentTag(tagName, content);
     if (typeAnnotation) {
@@ -249,14 +265,14 @@ function blockTag(comment, lexer, config, i18n, warning, files) {
  * The `@default` tag gets a special case because otherwise we will produce many warnings
  * about unescaped/mismatched/missing braces in legacy JSDoc comments
  */
-function defaultBlockContent(comment, lexer, config, i18n, warning, files) {
+function defaultBlockContent(comment, lexer, config, warning, validationWarning, files) {
     lexer.mark();
     const tempRegistry = new FileRegistry();
-    const content = blockContent(comment, lexer, config, i18n, () => { }, tempRegistry);
+    const content = blockContent(comment, lexer, config, () => { }, () => { }, tempRegistry);
     const end = lexer.done() || lexer.peek();
     lexer.release();
     if (content.some((part) => part.kind === "code" || part.kind === "inline-tag")) {
-        return blockContent(comment, lexer, config, i18n, warning, files);
+        return blockContent(comment, lexer, config, warning, validationWarning, files);
     }
     const tokens = [];
     while ((lexer.done() || lexer.peek()) !== end) {
@@ -279,10 +295,10 @@ function defaultBlockContent(comment, lexer, config, i18n, warning, files) {
  *
  * In TSDoc, we also want to treat the first line of the block as the example name.
  */
-function exampleBlock(comment, lexer, config, i18n, warning, files) {
+function exampleBlock(comment, lexer, config, warning, validationWarning, files) {
     lexer.mark();
     const tempRegistry = new FileRegistry();
-    const content = blockContent(comment, lexer, config, i18n, () => { }, tempRegistry);
+    const content = blockContent(comment, lexer, config, () => { }, () => { }, tempRegistry);
     const end = lexer.done() || lexer.peek();
     lexer.release();
     if (!config.jsDocCompatibility.exampleTag ||
@@ -323,7 +339,7 @@ function exampleBlock(comment, lexer, config, i18n, warning, files) {
                     assertNever(next.kind);
             }
         }
-        const content = blockContent(comment, lexer, config, i18n, warning, files);
+        const content = blockContent(comment, lexer, config, warning, validationWarning, files);
         const tag = new CommentTag("@example", content);
         if (exampleName.trim()) {
             tag.name = exampleName.trim();
@@ -362,7 +378,7 @@ function exampleBlock(comment, lexer, config, i18n, warning, files) {
  * If you change this, also look at parseCommentString as it
  * likely needs similar modifications to ensure parsing is consistent.
  */
-function blockContent(comment, lexer, config, i18n, warning, files) {
+function blockContent(comment, lexer, config, warning, validationWarning, files) {
     const content = [];
     let atNewLine = true;
     const reentry = new TextParserReentryState();
@@ -375,8 +391,16 @@ function blockContent(comment, lexer, config, i18n, warning, files) {
                 content.push({ kind: "text", text: next.text });
                 break;
             case TokenSyntaxKind.Text:
-                textContent(comment.sourcePath, next, i18n, warning, 
-                /*out*/ content, files, atNewLine, reentry);
+                textContent({
+                    sourcePath: comment.sourcePath,
+                    token: next,
+                    files,
+                    atNewLine,
+                    warning,
+                    validationWarning,
+                    validationOptions: config.validationOptions,
+                }, 
+                /*out*/ content, reentry);
                 break;
             case TokenSyntaxKind.Code:
                 content.push({ kind: "code", text: next.text });
@@ -414,7 +438,7 @@ function blockContent(comment, lexer, config, i18n, warning, files) {
                 content.push({ kind: "text", text: next.text });
                 break;
             case TokenSyntaxKind.OpenBrace:
-                inlineTag(lexer, content, config, i18n, warning);
+                inlineTag(lexer, content, config, warning);
                 consume = false;
                 break;
             default:
@@ -451,7 +475,7 @@ function blockContent(comment, lexer, config, i18n, warning, files) {
     }
     return content;
 }
-function inlineTag(lexer, block, config, i18n, warning) {
+function inlineTag(lexer, block, config, warning) {
     const openBrace = lexer.take();
     // Now skip whitespace to grab the tag name.
     // If the first non-whitespace text after the brace isn't a tag,

package/dist/lib/converter/comments/textParser.d.ts

@@ -1,15 +1,18 @@
-/**
- * Parser to handle plain text markdown.
- *
- * Responsible for recognizing relative paths within the text and turning
- * them into references.
- * @module
- */
-import type { TranslationProxy } from "../../internationalization/index.js";
 import type { CommentDisplayPart } from "../../models/index.js";
 import type { FileRegistry } from "../../models/FileRegistry.js";
+import { type ValidationOptions } from "#node-utils";
 import { type Token } from "./lexer.js";
 import type { NormalizedPath, TranslatedString } from "#utils";
+interface TextParserData {
+    sourcePath: NormalizedPath;
+    token: Token;
+    pos: number;
+    warning: (msg: TranslatedString, token: Token) => void;
+    validationWarning: (msg: TranslatedString, token: Token) => void;
+    files: FileRegistry;
+    atNewLine: boolean;
+    validationOptions: ValidationOptions;
+}
 /**
  * This is incredibly unfortunate. The comment lexer owns the responsibility
  * for splitting up text into text/code, this is totally fine for HTML links
@@ -26,4 +29,5 @@ export declare class TextParserReentryState {
  * Look for relative links within a piece of text and add them to the {@link FileRegistry}
  * so that they can be correctly resolved during rendering.
  */
-export declare function textContent(sourcePath: NormalizedPath, token: Token, i18n: TranslationProxy, warning: (msg: TranslatedString, token: Token) => void, outContent: CommentDisplayPart[], files: FileRegistry, atNewLine: boolean, reentry: TextParserReentryState): void;
+export declare function textContent(parserData: Omit<TextParserData, "pos">, outContent: CommentDisplayPart[], reentry: TextParserReentryState): void;
+export {};

package/dist/lib/converter/comments/textParser.js

@@ -1,3 +1,11 @@
+/**
+ * Parser to handle plain text markdown.
+ *
+ * Responsible for recognizing relative paths within the text and turning
+ * them into references.
+ * @module
+ */
+import { i18n } from "#utils";
 import { HtmlAttributeParser, ParserState } from "#node-utils";
 import { TokenSyntaxKind } from "./lexer.js";
 import MarkdownIt from "markdown-it";
@@ -34,42 +42,38 @@ export class TextParserReentryState {
  * Look for relative links within a piece of text and add them to the {@link FileRegistry}
  * so that they can be correctly resolved during rendering.
  */
-export function textContent(sourcePath, token, i18n, warning, outContent, files, atNewLine, reentry) {
+export function textContent(parserData, outContent, reentry) {
     let lastPartEnd = 0;
     let canEndMarkdownLink = true;
     const data = {
-        sourcePath,
-        token,
+        ...parserData,
         pos: 0, // relative to the token
-        warning,
-        files: files,
-        atNewLine,
     };
     function addRef(ref) {
         canEndMarkdownLink = true;
         outContent.push({
             kind: "text",
-            text: token.text.slice(lastPartEnd, ref.pos),
+            text: data.token.text.slice(lastPartEnd, ref.pos),
         });
         const link = {
             kind: "relative-link",
-            text: token.text.slice(ref.pos, ref.end),
+            text: data.token.text.slice(ref.pos, ref.end),
             target: ref.target,
             targetAnchor: ref.targetAnchor,
         };
         outContent.push(link);
         lastPartEnd = ref.end;
         data.pos = ref.end;
-        if (!ref.target) {
-            warning(i18n.relative_path_0_is_not_a_file_and_will_not_be_copied_to_output(token.text.slice(ref.pos, ref.end)), {
+        if (!ref.target && data.validationOptions.invalidPath) {
+            data.validationWarning(i18n.relative_path_0_is_not_a_file_and_will_not_be_copied_to_output(data.token.text.slice(ref.pos, ref.end)), {
                 kind: TokenSyntaxKind.Text,
                 // ref.pos is relative to the token, but this pos is relative to the file.
-                pos: token.pos + ref.pos,
-                text: token.text.slice(ref.pos, ref.end),
+                pos: data.token.pos + ref.pos,
+                text: data.token.text.slice(ref.pos, ref.end),
             });
         }
     }
-    while (data.pos < token.text.length) {
+    while (data.pos < data.token.text.length) {
         if (canEndMarkdownLink) {
             const link = checkMarkdownLink(data, reentry);
             if (link) {
@@ -92,14 +96,14 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
             }
             continue;
         }
-        const atNewLine = token.text[data.pos] === "\n";
+        const atNewLine = data.token.text[data.pos] === "\n";
         data.atNewLine = atNewLine;
         if (atNewLine && !reentry.withinLinkDest)
             canEndMarkdownLink = true;
         ++data.pos;
     }
-    if (lastPartEnd !== token.text.length) {
-        outContent.push({ kind: "text", text: token.text.slice(lastPartEnd) });
+    if (lastPartEnd !== data.token.text.length) {
+        outContent.push({ kind: "text", text: data.token.text.slice(lastPartEnd) });
     }
 }
 /**
@@ -245,6 +249,7 @@ function checkTagLink(data) {
     if (token.text.startsWith("<link ", pos)) {
         data.pos += 4;
         return checkAttributes(data, {
+            // cspell:words imagesrcset
             imagesrcset: checkAttributeSrcSet,
         });
     }

package/dist/lib/converter/converter.js

@@ -614,6 +614,7 @@ let Converter = (() => {
                 suppressCommentWarningsInDeclarationFiles: this.application.options.getValue("suppressCommentWarningsInDeclarationFiles"),
                 useTsLinkResolution: this.application.options.getValue("useTsLinkResolution"),
                 commentStyle: this.application.options.getValue("commentStyle"),
+                validationOptions: this.application.options.getValue("validation"),
             };
             // Can't be included in options because the TSDoc parser blows up if we do.
             // TypeDoc supports it as one, so it should always be included here.

package/dist/lib/converter/factories/signature.d.ts

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import { ParameterReflection, type Reflection, ReflectionKind, SignatureReflection, TypeParameterReflection } from "../../models/index.js";
 import type { Context } from "../context.js";
+export declare function convertConstructSignatures(context: Context, symbol: ts.Symbol): void;
 export declare function createSignature(context: Context, kind: ReflectionKind.CallSignature | ReflectionKind.ConstructorSignature | ReflectionKind.GetSignature | ReflectionKind.SetSignature, signature: ts.Signature, symbol: ts.Symbol | undefined, declaration?: ts.SignatureDeclaration | ts.JSDocSignature): void;
 /**
  * Special cased constructor factory for functions tagged with `@class`

package/dist/lib/converter/factories/signature.js

@@ -4,6 +4,19 @@ import { DeclarationReflection, IntrinsicType, ParameterReflection, PredicateTyp
 import { ConverterEvents } from "../converter-events.js";
 import { convertDefaultValue } from "../convert-expression.js";
 import { removeUndefined } from "../utils/reflections.js";
+export function convertConstructSignatures(context, symbol) {
+    const type = context.checker.getDeclaredTypeOfSymbol(symbol);
+    // These get added as a "constructor" member of this interface. This is a problem... but nobody
+    // has complained yet. We really ought to have a constructSignatures property on the reflection instead.
+    const constructSignatures = context.checker.getSignaturesOfType(type, ts.SignatureKind.Construct);
+    if (constructSignatures.length) {
+        const constructMember = new DeclarationReflection("constructor", ReflectionKind.Constructor, context.scope);
+        context.postReflectionCreation(constructMember, symbol, void 0);
+        context.finalizeDeclarationReflection(constructMember);
+        const constructContext = context.withScope(constructMember);
+        constructSignatures.forEach((sig) => createSignature(constructContext, ReflectionKind.ConstructorSignature, sig, symbol));
+    }
+}
 export function createSignature(context, kind, signature, symbol, declaration) {
     assert(context.scope instanceof DeclarationReflection);
     declaration ||= signature.getDeclaration();

package/dist/lib/converter/jsdoc.d.ts

@@ -1,4 +1,4 @@
 import ts from "typescript";
 import type { Context } from "./context.js";
-export declare function convertJsDocAlias(context: Context, symbol: ts.Symbol, declaration: ts.JSDocTypedefTag | ts.JSDocEnumTag, exportSymbol?: ts.Symbol): void;
+export declare function convertJsDocAlias(context: Context, symbol: ts.Symbol, declaration: ts.JSDocTypedefTag | ts.JSDocEnumTag, exportSymbol?: ts.Symbol): undefined;
 export declare function convertJsDocCallback(context: Context, symbol: ts.Symbol, declaration: ts.JSDocCallbackTag, exportSymbol?: ts.Symbol): void;

package/dist/lib/converter/jsdoc.js

@@ -5,13 +5,44 @@ import { ok } from "assert";
 import ts from "typescript";
 import { DeclarationReflection, IntrinsicType, ReflectionKind, ReflectionType, SignatureReflection, } from "../models/index.js";
 import { ConverterEvents } from "./converter-events.js";
-import { convertParameterNodes, convertTemplateParameterNodes } from "./factories/signature.js";
+import { convertConstructSignatures, convertParameterNodes, convertTemplateParameterNodes, createSignature, } from "./factories/signature.js";
+import { i18n } from "#utils";
+import { convertIndexSignatures } from "./factories/index-signature.js";
+// This is almost convertTypeAliasAsInterface, but unfortunately needs to be separate
+// due to type parameters being different in JSDoc comments
+function convertJsDocAliasAsInterface(context, symbol, exportSymbol, declaration) {
+    const reflection = context.createDeclarationReflection(ReflectionKind.Interface, symbol, exportSymbol);
+    context.finalizeDeclarationReflection(reflection);
+    const rc = context.withScope(reflection);
+    const type = context.checker.getTypeAtLocation(declaration);
+    if (type.getFlags() & ts.TypeFlags.Union) {
+        context.logger.warn(i18n.converting_union_as_interface(), declaration);
+    }
+    // Interfaces have properties
+    for (const prop of type.getProperties()) {
+        context.converter.convertSymbol(rc, prop);
+    }
+    // And type parameters
+    convertTemplateParameters(rc, declaration.parent);
+    // And maybe call signatures
+    context.checker
+        .getSignaturesOfType(type, ts.SignatureKind.Call)
+        .forEach((sig) => createSignature(rc, ReflectionKind.CallSignature, sig, symbol));
+    // And maybe constructor signatures
+    convertConstructSignatures(rc, symbol);
+    // And finally, index signatures
+    convertIndexSignatures(rc, type);
+}
 export function convertJsDocAlias(context, symbol, declaration, exportSymbol) {
     if (declaration.typeExpression &&
         ts.isJSDocTypeLiteral(declaration.typeExpression)) {
         convertJsDocInterface(context, declaration, symbol, exportSymbol);
         return;
     }
+    const comment = context.getJsDocComment(declaration);
+    if (comment?.hasModifier("@interface")) {
+        return convertJsDocAliasAsInterface(context, symbol, exportSymbol, declaration);
+    }
     // If the typedef tag is just referring to another type-space symbol, with no type parameters
     // or appropriate forwarding type parameters, then we treat it as a re-export instead of creating
     // a type alias with an import type.
@@ -21,7 +52,7 @@ export function convertJsDocAlias(context, symbol, declaration, exportSymbol) {
         return;
     }
     const reflection = context.createDeclarationReflection(ReflectionKind.TypeAlias, symbol, exportSymbol);
-    reflection.comment = context.getJsDocComment(declaration);
+    reflection.comment = comment;
     reflection.type = context.converter.convertType(context.withScope(reflection), declaration.typeExpression?.type);
     convertTemplateParameters(context.withScope(reflection), declaration.parent);
     context.finalizeDeclarationReflection(reflection);

package/dist/lib/converter/plugins/CommentPlugin.js

@@ -290,6 +290,8 @@ let CommentPlugin = (() => {
          * @param reflection  The reflection that is currently processed.
          */
         onCreateTypeParameter(_context, reflection) {
+            if (reflection.comment)
+                return;
             const comment = reflection.parent?.comment;
             if (comment) {
                 let tag = comment.getIdentifiedTag(reflection.name, "@typeParam");
@@ -306,6 +308,17 @@ let CommentPlugin = (() => {
                     reflection.comment = new Comment(tag.content);
                     reflection.comment.sourcePath = comment.sourcePath;
                     removeIfPresent(comment.blockTags, tag);
+                    return;
+                }
+            }
+            // #3031 if this is a class constructor, also check for type parameters
+            // that live on the class itself and potentially copy their comment.
+            if (reflection.parent?.kindOf(ReflectionKind.ConstructorSignature) &&
+                reflection.parent.parent?.kindOf(ReflectionKind.Constructor)) {
+                const cls = reflection.parent.parent.parent;
+                const typeParam = cls.typeParameters?.find(param => param.name === reflection.name);
+                if (typeParam?.comment) {
+                    reflection.comment = typeParam.comment.clone();
                 }
             }
         }

package/dist/lib/converter/plugins/ImplementsPlugin.d.ts

@@ -14,6 +14,7 @@ export declare class ImplementsPlugin extends ConverterComponent {
      */
     private analyzeImplements;
     private analyzeInheritance;
+    private cleanUpImplements;
     private onResolveEnd;
     private onRevive;
     private resolve;