typedoc 0.28.13 → 0.28.15

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,6 +1,6 @@
 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 type { Context } from "../context.js";
@@ -8,10 +8,12 @@ export interface CommentParserConfig {
     blockTags: Set<string>;
     inlineTags: Set<string>;
     modifierTags: Set<string>;
+    preservedTypeAnnotationTags: Set<string>;
     jsDocCompatibility: JsDocCompatibility;
     suppressCommentWarningsInDeclarationFiles: boolean;
     useTsLinkResolution: boolean;
     commentStyle: CommentStyle;
+    validationOptions: ValidationOptions;
 }
 export interface CommentContext {
     config: CommentParserConfig;

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,29 +236,43 @@ 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);
     }
-    else if (["@default", "@defaultValue"].includes(tagName) &&
+    let typeAnnotation;
+    if (!lexer.done() &&
+        config.preservedTypeAnnotationTags.has(tagName)) {
+        if (lexer.peek().kind === TokenSyntaxKind.Text && /^\s+$/.test(lexer.peek().text)) {
+            lexer.take();
+        }
+        if (lexer.peek().kind === TokenSyntaxKind.TypeAnnotation) {
+            typeAnnotation = lexer.take().text;
+        }
+    }
+    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) {
+        tag.typeAnnotation = typeAnnotation;
     }
-    return new CommentTag(tagName, content);
+    return tag;
 }
 /**
  * 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) {
@@ -265,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 ||
@@ -309,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();
@@ -348,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();
@@ -361,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 });
@@ -400,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:
@@ -437,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

@@ -609,10 +609,12 @@ let Converter = (() => {
                 blockTags: new Set(this.application.options.getValue("blockTags")),
                 inlineTags: new Set(this.application.options.getValue("inlineTags")),
                 modifierTags: new Set(this.application.options.getValue("modifierTags")),
+                preservedTypeAnnotationTags: new Set(this.application.options.getValue("preservedTypeAnnotationTags")),
                 jsDocCompatibility: this.application.options.getValue("jsDocCompatibility"),
                 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.js

@@ -113,7 +113,7 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         assert(!declaration ||
             ts.isParameter(declaration) ||
             ts.isJSDocParameterTag(declaration));
-        const paramRefl = new ParameterReflection(/__\d+/.test(param.name) ? "__namedParameters" : param.name, ReflectionKind.Parameter, sigRef);
+        const paramRefl = new ParameterReflection(/^__\d+$/.test(param.name) ? "__namedParameters" : param.name, ReflectionKind.Parameter, sigRef);
         if (declaration && ts.isJSDocParameterTag(declaration)) {
             paramRefl.comment = context.getJsDocComment(declaration);
         }
@@ -132,7 +132,7 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
             }
         }
         else {
-            type = param.type;
+            type = context.checker.getTypeOfSymbol(param);
         }
         if (declaration &&
             ts.isParameter(declaration) &&
@@ -160,8 +160,9 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         paramRefl.defaultValue = convertDefaultValue(parameterNodes?.[i + parameterNodeOffset]);
         paramRefl.setFlag(ReflectionFlag.Optional, isOptional);
         // If we have no declaration, then this is an implicitly defined parameter in JS land
-        // because the method body uses `arguments`... which is always a rest argument
-        let isRest = true;
+        // because the method body uses `arguments`... which is always a rest argument,
+        // unless it is a this parameter defined with @this in JSDoc.
+        let isRest = param.name !== "this";
         if (declaration) {
             isRest = ts.isParameter(declaration)
                 ? !!declaration.dotDotDotToken

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

@@ -61,6 +61,7 @@ export declare class CommentPlugin extends ConverterComponent {
     accessor cascadedModifierTags: TagString[];
     accessor excludeInternal: boolean;
     accessor excludePrivate: boolean;
+    accessor excludePrivateClassFields: boolean;
     accessor excludeProtected: boolean;
     accessor excludeNotDocumented: boolean;
     accessor excludeCategories: string[];

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

@@ -44,9 +44,9 @@ import { CategoryPlugin } from "./CategoryPlugin.js";
  * (for JS users) will be consumed by TypeScript and need not be preserved
  * in the comment.
  *
- * Note that param/arg/argument/return/returns are not present.
+ * Note that param/arg/argument/return/returns/this are not present.
  * These tags will have their type information stripped when parsing, but still
- * provide useful information for documentation.
+ * may provide useful information for documentation.
  */
 const NEVER_RENDERED = [
     "@augments",
@@ -55,7 +55,6 @@ const NEVER_RENDERED = [
     "@constructor",
     "@enum",
     "@extends",
-    "@this",
     "@type",
     "@typedef",
     "@jsx",
@@ -140,6 +139,9 @@ let CommentPlugin = (() => {
     let _excludePrivate_decorators;
     let _excludePrivate_initializers = [];
     let _excludePrivate_extraInitializers = [];
+    let _excludePrivateClassFields_decorators;
+    let _excludePrivateClassFields_initializers = [];
+    let _excludePrivateClassFields_extraInitializers = [];
     let _excludeProtected_decorators;
     let _excludeProtected_initializers = [];
     let _excludeProtected_extraInitializers = [];
@@ -159,6 +161,7 @@ let CommentPlugin = (() => {
             _cascadedModifierTags_decorators = [Option("cascadedModifierTags")];
             _excludeInternal_decorators = [Option("excludeInternal")];
             _excludePrivate_decorators = [Option("excludePrivate")];
+            _excludePrivateClassFields_decorators = [Option("excludePrivateClassFields")];
             _excludeProtected_decorators = [Option("excludeProtected")];
             _excludeNotDocumented_decorators = [Option("excludeNotDocumented")];
             _excludeCategories_decorators = [Option("excludeCategories")];
@@ -167,6 +170,7 @@ let CommentPlugin = (() => {
             __esDecorate(this, null, _cascadedModifierTags_decorators, { kind: "accessor", name: "cascadedModifierTags", static: false, private: false, access: { has: obj => "cascadedModifierTags" in obj, get: obj => obj.cascadedModifierTags, set: (obj, value) => { obj.cascadedModifierTags = value; } }, metadata: _metadata }, _cascadedModifierTags_initializers, _cascadedModifierTags_extraInitializers);
             __esDecorate(this, null, _excludeInternal_decorators, { kind: "accessor", name: "excludeInternal", static: false, private: false, access: { has: obj => "excludeInternal" in obj, get: obj => obj.excludeInternal, set: (obj, value) => { obj.excludeInternal = value; } }, metadata: _metadata }, _excludeInternal_initializers, _excludeInternal_extraInitializers);
             __esDecorate(this, null, _excludePrivate_decorators, { kind: "accessor", name: "excludePrivate", static: false, private: false, access: { has: obj => "excludePrivate" in obj, get: obj => obj.excludePrivate, set: (obj, value) => { obj.excludePrivate = value; } }, metadata: _metadata }, _excludePrivate_initializers, _excludePrivate_extraInitializers);
+            __esDecorate(this, null, _excludePrivateClassFields_decorators, { kind: "accessor", name: "excludePrivateClassFields", static: false, private: false, access: { has: obj => "excludePrivateClassFields" in obj, get: obj => obj.excludePrivateClassFields, set: (obj, value) => { obj.excludePrivateClassFields = value; } }, metadata: _metadata }, _excludePrivateClassFields_initializers, _excludePrivateClassFields_extraInitializers);
             __esDecorate(this, null, _excludeProtected_decorators, { kind: "accessor", name: "excludeProtected", static: false, private: false, access: { has: obj => "excludeProtected" in obj, get: obj => obj.excludeProtected, set: (obj, value) => { obj.excludeProtected = value; } }, metadata: _metadata }, _excludeProtected_initializers, _excludeProtected_extraInitializers);
             __esDecorate(this, null, _excludeNotDocumented_decorators, { kind: "accessor", name: "excludeNotDocumented", static: false, private: false, access: { has: obj => "excludeNotDocumented" in obj, get: obj => obj.excludeNotDocumented, set: (obj, value) => { obj.excludeNotDocumented = value; } }, metadata: _metadata }, _excludeNotDocumented_initializers, _excludeNotDocumented_extraInitializers);
             __esDecorate(this, null, _excludeCategories_decorators, { kind: "accessor", name: "excludeCategories", static: false, private: false, access: { has: obj => "excludeCategories" in obj, get: obj => obj.excludeCategories, set: (obj, value) => { obj.excludeCategories = value; } }, metadata: _metadata }, _excludeCategories_initializers, _excludeCategories_extraInitializers);
@@ -185,7 +189,10 @@ let CommentPlugin = (() => {
         #excludePrivate_accessor_storage = (__runInitializers(this, _excludeInternal_extraInitializers), __runInitializers(this, _excludePrivate_initializers, void 0));
         get excludePrivate() { return this.#excludePrivate_accessor_storage; }
         set excludePrivate(value) { this.#excludePrivate_accessor_storage = value; }
-        #excludeProtected_accessor_storage = (__runInitializers(this, _excludePrivate_extraInitializers), __runInitializers(this, _excludeProtected_initializers, void 0));
+        #excludePrivateClassFields_accessor_storage = (__runInitializers(this, _excludePrivate_extraInitializers), __runInitializers(this, _excludePrivateClassFields_initializers, void 0));
+        get excludePrivateClassFields() { return this.#excludePrivateClassFields_accessor_storage; }
+        set excludePrivateClassFields(value) { this.#excludePrivateClassFields_accessor_storage = value; }
+        #excludeProtected_accessor_storage = (__runInitializers(this, _excludePrivateClassFields_extraInitializers), __runInitializers(this, _excludeProtected_initializers, void 0));
         get excludeProtected() { return this.#excludeProtected_accessor_storage; }
         set excludeProtected(value) { this.#excludeProtected_accessor_storage = value; }
         #excludeNotDocumented_accessor_storage = (__runInitializers(this, _excludeProtected_extraInitializers), __runInitializers(this, _excludeNotDocumented_initializers, void 0));
@@ -283,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");
@@ -299,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();
                 }
             }
         }
@@ -447,19 +467,25 @@ let CommentPlugin = (() => {
         moveSignatureParamComments(signature, comment = signature.comment) {
             if (!comment)
                 return;
-            signature.parameters?.forEach((parameter, index) => {
-                if (parameter.name === "__namedParameters") {
-                    const commentParams = comment.blockTags.filter((tag) => tag.tag === "@param" && !tag.name?.includes("."));
-                    if (signature.parameters?.length === commentParams.length &&
-                        commentParams[index].name) {
-                        parameter.name = commentParams[index].name;
-                    }
+            const unusedCommentParams = comment.blockTags.filter((tag) => tag.tag === "@param" && tag.name && !tag.name.includes(".") &&
+                !signature.parameters?.some(p => p.name === tag.name));
+            signature.parameters?.forEach((parameter) => {
+                if (parameter.name === "__namedParameters" && unusedCommentParams.length) {
+                    parameter.name = unusedCommentParams[0].name;
+                    unusedCommentParams.splice(0, 1);
                 }
                 const tag = comment.getIdentifiedTag(parameter.name, "@param");
                 if (tag) {
                     parameter.comment = new Comment(Comment.cloneDisplayParts(tag.content));
                     parameter.comment.sourcePath = comment.sourcePath;
                 }
+                else if (parameter.name === "this") {
+                    const thisTag = comment.getTag("@this");
+                    if (thisTag) {
+                        parameter.comment = new Comment(Comment.cloneDisplayParts(thisTag.content));
+                        parameter.comment.sourcePath = comment.sourcePath;
+                    }
+                }
             });
             for (const parameter of signature.typeParameters || []) {
                 const tag = comment.getIdentifiedTag(parameter.name, "@typeParam") ||
@@ -471,6 +497,7 @@ let CommentPlugin = (() => {
                 }
             }
             this.validateParamTags(signature, comment, signature.parameters || []);
+            comment.removeTags("@this");
             comment.removeTags("@param");
             comment.removeTags("@typeParam");
             comment.removeTags("@template");
@@ -513,6 +540,16 @@ let CommentPlugin = (() => {
                 this.excludePrivate) {
                 return true;
             }
+            // #3017 this isn't quite right as it may incorrectly detect
+            // private members named with a hash which aren't actually private
+            // class fields (e.g. class Foo { "#hash" = 1 })
+            // We can't fix this without storing more information about the name,
+            // which I'm going to put off until #3015 is done.
+            if (reflection.flags.hasFlag(ReflectionFlag.Private) &&
+                reflection.name.startsWith("#") &&
+                this.excludePrivateClassFields) {
+                return true;
+            }
             if (reflection.flags.hasFlag(ReflectionFlag.Protected) &&
                 this.excludeProtected) {
                 return true;

package/dist/lib/converter/symbols.js

@@ -377,6 +377,14 @@ function convertClassOrInterface(context, symbol, exportSymbol) {
         reflection.implementedTypes = implementedTypes;
     }
     context.finalizeDeclarationReflection(reflection);
+    // Convert type parameters early so that we get access them when converting the constructors if any
+    if (instanceType.typeParameters) {
+        reflection.typeParameters = instanceType.typeParameters.map((param) => {
+            const declaration = param.symbol.declarations?.[0];
+            assert(declaration && ts.isTypeParameterDeclaration(declaration));
+            return createTypeParamReflection(declaration, reflectionContext);
+        });
+    }
     if (classDeclaration && reflection.kind === ReflectionKind.Class) {
         // Classes can have static props
         const staticType = context.checker.getTypeOfSymbolAtLocation(symbol, classDeclaration);
@@ -404,14 +412,6 @@ function convertClassOrInterface(context, symbol, exportSymbol) {
     }
     // Classes/interfaces usually just have properties...
     convertSymbols(reflectionContext, context.checker.getPropertiesOfType(instanceType));
-    // And type arguments
-    if (instanceType.typeParameters) {
-        reflection.typeParameters = instanceType.typeParameters.map((param) => {
-            const declaration = param.symbol.declarations?.[0];
-            assert(declaration && ts.isTypeParameterDeclaration(declaration));
-            return createTypeParamReflection(declaration, reflectionContext);
-        });
-    }
     // Interfaces might also have call signatures
     // Classes might too, because of declaration merging
     context.checker
@@ -754,6 +754,13 @@ function convertAccessor(context, symbol, exportSymbol) {
     const declaration = symbol.getDeclarations()?.[0];
     if (declaration) {
         setModifiers(symbol, declaration, reflection);
+        // #3019, auto accessors `accessor x: string` get the symbol flag for
+        // an accessor, but they don't have get/set accessors, so the need a type
+        // set on the accessor reflection structure.
+        if (ts.isPropertyDeclaration(declaration) &&
+            declaration.modifiers?.some(n => n.kind === ts.SyntaxKind.AccessorKeyword)) {
+            reflection.type = context.converter.convertType(context.withScope(reflection), context.checker.getTypeOfSymbol(symbol), declaration.type);
+        }
     }
     context.finalizeDeclarationReflection(reflection);
     const getDeclaration = symbol.getDeclarations()?.find(ts.isGetAccessor);

package/dist/lib/converter/types.js

@@ -696,7 +696,7 @@ const unionConverter = {
     convertType(context, type) {
         const types = type.types.map((type) => convertType(context, type));
         normalizeUnion(types);
-        sortLiteralUnion(types);
+        sortUnion(types);
         return new UnionType(types);
     },
 };
@@ -764,14 +764,26 @@ function kindToModifier(kind) {
             return undefined;
     }
 }
-function sortLiteralUnion(types) {
-    if (types.some((t) => t.type !== "literal" || typeof t.value !== "number")) {
+function sortUnion(types) {
+    // If every member of the union is a literal numeric type, sort in ascending order
+    if (types.every(t => t.type === "literal" && typeof t.value === "number")) {
+        types.sort((a, b) => {
+            const aLit = a;
+            const bLit = b;
+            return aLit.value - bLit.value;
+        });
         return;
     }
+    // #3024 Otherwise, leave the union in the converted order with the exception of null
+    // and undefined, which should be sorted last, with null before undefined.
     types.sort((a, b) => {
-        const aLit = a;
-        const bLit = b;
-        return aLit.value - bLit.value;
+        const aIsNull = a.type === "literal" && a.value === null;
+        const aIsUndef = a.type === "intrinsic" && a.name === "undefined";
+        const bIsNull = b.type === "literal" && b.value === null;
+        const bIsUndef = b.type === "intrinsic" && b.name === "undefined";
+        const aWeight = aIsNull ? 1 : aIsUndef ? 2 : 0;
+        const bWeight = bIsNull ? 1 : bIsUndef ? 2 : 0;
+        return aWeight - bWeight;
     });
 }
 function normalizeUnion(types) {

package/dist/lib/converter/utils/repository.js

@@ -139,6 +139,9 @@ let GitRepository = (() => {
          * @returns A new instance of {@link GitRepository} or undefined.
          */
         static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
+            if (gitRevision === "{branch}") {
+                gitRevision = git("-C", path, "branch", "--show-current").stdout.trim();
+            }
             gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
             if (gitRevision == "HEAD")
                 return; // Will only happen in a repo with no commits.

package/dist/lib/internationalization/locales/de.cjs

@@ -165,7 +165,6 @@ module.exports = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "Arten von Reflections, die von excludeNotDocumented entfernt werden können",
     help_excludeInternal: "Verhindert, dass Symbole in der Dokumentation erscheinen, die mit @internal markiert sind",
     help_excludeCategories: "Schließt Symbole aus dieser Kategorie von der Dokumentation aus",
-    help_excludePrivate: "Ignoriert private Variablen und Methoden, Standardwert ist true.",
     help_excludeProtected: "Ignoriert geschützte Variablen und Methoden",
     help_excludeReferences: "Wird ein Symbol mehrfach exportiert, ignoriere alle außer dem ersten Export",
     help_externalSymbolLinkMappings: "Definiert eigene Links für Symbole, die nicht in der Dokumentation enthalten sind",