typedoc 0.28.12 → 0.28.14

package/dist/lib/application.d.ts

@@ -67,6 +67,10 @@ export declare class Application extends AbstractComponent<Application, Applicat
      */
     internationalization: Internationalization;
     options: Options;
+    /**
+     * Due for deprecation in 0.29, use the reference to this on {@link ProjectReflection},
+     * this was the wrong place for this member to live.
+     */
     files: FileRegistry;
     /** @internal */
     accessor lang: string;

package/dist/lib/application.js

@@ -158,6 +158,10 @@ let Application = (() => {
          */
         internationalization = new Internationalization();
         options = new Options();
+        /**
+         * Due for deprecation in 0.29, use the reference to this on {@link ProjectReflection},
+         * this was the wrong place for this member to live.
+         */
         files = new ValidatingFileRegistry();
         #lang_accessor_storage = __runInitializers(this, _lang_initializers, void 0);
         /** @internal */
@@ -260,6 +264,9 @@ let Application = (() => {
             else {
                 this.logger.level = this.options.getValue("logLevel");
             }
+            if (this.files instanceof ValidatingFileRegistry) {
+                this.files.basePath = this.options.getValue("basePath");
+            }
             for (const [lang, locales] of Object.entries(this.options.getValue("locales"))) {
                 this.internationalization.addTranslations(lang, locales);
             }
@@ -630,7 +637,7 @@ let Application = (() => {
             for (const { dir, options } of projectsToConvert) {
                 this.logger.info(i18n.converting_project_at_0(nicePath(dir)));
                 this.options = options;
-                this.files = new ValidatingFileRegistry();
+                this.files = new ValidatingFileRegistry(options.getValue("basePath"));
                 let project = await this.convert();
                 if (project) {
                     this.validate(project);

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

@@ -8,6 +8,7 @@ export interface CommentParserConfig {
     blockTags: Set<string>;
     inlineTags: Set<string>;
     modifierTags: Set<string>;
+    preservedTypeAnnotationTags: Set<string>;
     jsDocCompatibility: JsDocCompatibility;
     suppressCommentWarningsInDeclarationFiles: boolean;
     useTsLinkResolution: boolean;

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

@@ -206,6 +206,9 @@ function postProcessComment(comment, i18n, getPosition, warning) {
     if ((inlineInheritDoc.length || inheritDoc.length) && remarks.length) {
         warning(i18n.content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0(getPosition()));
     }
+    if ((inlineInheritDoc.length || inheritDoc.length) && returns.length) {
+        warning(i18n.content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0(getPosition()));
+    }
 }
 const aliasedTags = new Map([["@return", "@returns"]]);
 function blockTag(comment, lexer, config, i18n, warning, files) {
@@ -219,14 +222,28 @@ function blockTag(comment, lexer, config, i18n, warning, files) {
     if (tagName === "@example") {
         return exampleBlock(comment, lexer, config, i18n, warning, 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);
     }
     else {
         content = blockContent(comment, lexer, config, i18n, warning, files);
     }
-    return new CommentTag(tagName, content);
+    const tag = new CommentTag(tagName, content);
+    if (typeAnnotation) {
+        tag.typeAnnotation = typeAnnotation;
+    }
+    return tag;
 }
 /**
  * The `@default` tag gets a special case because otherwise we will produce many warnings

package/dist/lib/converter/converter.js

@@ -609,6 +609,7 @@ 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"),

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));
@@ -447,19 +454,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 +484,7 @@ let CommentPlugin = (() => {
                 }
             }
             this.validateParamTags(signature, comment, signature.parameters || []);
+            comment.removeTags("@this");
             comment.removeTags("@param");
             comment.removeTags("@typeParam");
             comment.removeTags("@template");
@@ -513,6 +527,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/plugins/ImplementsPlugin.js

@@ -4,7 +4,7 @@ import { DeclarationReflection, ReflectionFlag, ReflectionKind, SignatureReflect
 import { ReferenceType, ReflectionType } from "../../models/types.js";
 import { filterMap, zip } from "#utils";
 import { ConverterComponent } from "../components.js";
-import { getHumanName } from "../../utils/index.js";
+import { findPackageForPath, getHumanName } from "../../utils/index.js";
 import { ConverterEvents } from "../converter-events.js";
 /**
  * A plugin that detects interface implementations of functions and
@@ -95,22 +95,23 @@ export class ImplementsPlugin extends ConverterComponent {
         // serialization/deserialization, might point to an unexpected location. (See the mixin
         // converter tests, I suspect this might actually be an indication of something else slightly
         // broken there, but don't want to spend more time with this right now.)
-        // #2982, even more unfortunately, we only want to keep the link if it is pointing to a reflection
-        // which will receive a link during rendering.
-        const isValidRef = (ref) => ref.reflection && !ref.reflection.parent?.kindOf(ReflectionKind.TypeLiteral);
+        // #2982/#3007, even more unfortunately, we only want to keep the link if it is pointing
+        // to a reflection which will receive a link during rendering, we pick this based on it being
+        // the type of member we expect to point to.
+        const isValidRef = (ref) => !!ref.reflection?.parent?.kindOf(ReflectionKind.ClassOrInterface | ReflectionKind.Method | ReflectionKind.Constructor);
         for (const child of reflection.children || []) {
             if (child.inheritedFrom && !isValidRef(child.inheritedFrom)) {
-                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project);
+                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project, child.inheritedFrom.package);
             }
             if (child.overwrites && !isValidRef(child.overwrites)) {
-                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project);
+                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project, child.overwrites.package);
             }
             for (const childSig of child.getAllSignatures()) {
                 if (childSig.inheritedFrom && !isValidRef(childSig.inheritedFrom)) {
-                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project);
+                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project, childSig.inheritedFrom.package);
                 }
                 if (childSig.overwrites && !isValidRef(childSig.overwrites)) {
-                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project);
+                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project, childSig.overwrites.package);
                 }
             }
         }
@@ -325,15 +326,27 @@ export class ImplementsPlugin extends ConverterComponent {
         }
     }
 }
+function getConstructorPackagePath(context, clause) {
+    const symbol = context.getSymbolAtLocation(clause.expression);
+    if (!symbol)
+        return undefined;
+    const resolvedSymbol = context.resolveAliasedSymbol(symbol);
+    const symbolPath = resolvedSymbol?.declarations?.[0]?.getSourceFile().fileName;
+    if (!symbolPath)
+        return undefined;
+    return findPackageForPath(symbolPath)?.[0];
+}
 function constructorInheritance(context, reflection, childDecl, constructorDecl) {
     const extendsClause = childDecl.heritageClauses?.find((cl) => cl.token === ts.SyntaxKind.ExtendsKeyword);
     if (!extendsClause)
         return;
-    const name = `${extendsClause.types[0].getText()}.constructor`;
+    const extendsType = extendsClause.types[0];
+    const refPackage = getConstructorPackagePath(context, extendsType);
+    const name = `${extendsType.getText()}.constructor`;
     const key = constructorDecl ? "overwrites" : "inheritedFrom";
-    reflection[key] ??= ReferenceType.createBrokenReference(name, context.project);
+    reflection[key] ??= ReferenceType.createBrokenReference(name, context.project, refPackage);
     for (const sig of reflection.signatures ?? []) {
-        sig[key] ??= ReferenceType.createBrokenReference(name, context.project);
+        sig[key] ??= ReferenceType.createBrokenReference(name, context.project, refPackage);
     }
 }
 function findProperty(reflection, parent) {
@@ -356,7 +369,7 @@ function createLink(context, reflection, clause, expr, symbol, isInherit) {
     const rootSymbols = context.checker.getRootSymbols(symbol);
     const ref = rootSymbols.length && rootSymbols[0] != symbol
         ? context.createSymbolReference(rootSymbols[0], context, name)
-        : ReferenceType.createBrokenReference(name, context.project);
+        : ReferenceType.createBrokenReference(name, context.project, undefined);
     link(reflection);
     link(reflection.getSignature);
     link(reflection.setSignature);

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

@@ -149,6 +149,8 @@ let InheritDocPlugin = (() => {
                 return;
             }
             target.comment.removeTags("@inheritDoc");
+            target.comment.removeTags("@remarks");
+            target.comment.removeTags("@returns");
             target.comment.summary = Comment.cloneDisplayParts(source.comment.summary);
             const remarks = source.comment.getTag("@remarks");
             if (remarks) {

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

@@ -1,6 +1,5 @@
 import { ConverterComponent } from "../components.js";
 import type { Converter } from "../converter.js";
-import { type NormalizedPath } from "#utils";
 /**
  * A handler that attaches source file information to reflections.
  */
@@ -10,7 +9,7 @@ export declare class SourcePlugin extends ConverterComponent {
     accessor gitRemote: string;
     accessor disableGit: boolean;
     accessor sourceLinkTemplate: string;
-    accessor basePath: NormalizedPath;
+    get displayBasePath(): import("#utils").NormalizedPath;
     /**
      * All file names to find the base path from.
      */

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

@@ -62,9 +62,6 @@ let SourcePlugin = (() => {
     let _sourceLinkTemplate_decorators;
     let _sourceLinkTemplate_initializers = [];
     let _sourceLinkTemplate_extraInitializers = [];
-    let _basePath_decorators;
-    let _basePath_initializers = [];
-    let _basePath_extraInitializers = [];
     return class SourcePlugin extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -73,13 +70,11 @@ let SourcePlugin = (() => {
             _gitRemote_decorators = [Option("gitRemote")];
             _disableGit_decorators = [Option("disableGit")];
             _sourceLinkTemplate_decorators = [Option("sourceLinkTemplate")];
-            _basePath_decorators = [Option("basePath")];
             __esDecorate(this, null, _disableSources_decorators, { kind: "accessor", name: "disableSources", static: false, private: false, access: { has: obj => "disableSources" in obj, get: obj => obj.disableSources, set: (obj, value) => { obj.disableSources = value; } }, metadata: _metadata }, _disableSources_initializers, _disableSources_extraInitializers);
             __esDecorate(this, null, _gitRevision_decorators, { kind: "accessor", name: "gitRevision", static: false, private: false, access: { has: obj => "gitRevision" in obj, get: obj => obj.gitRevision, set: (obj, value) => { obj.gitRevision = value; } }, metadata: _metadata }, _gitRevision_initializers, _gitRevision_extraInitializers);
             __esDecorate(this, null, _gitRemote_decorators, { kind: "accessor", name: "gitRemote", static: false, private: false, access: { has: obj => "gitRemote" in obj, get: obj => obj.gitRemote, set: (obj, value) => { obj.gitRemote = value; } }, metadata: _metadata }, _gitRemote_initializers, _gitRemote_extraInitializers);
             __esDecorate(this, null, _disableGit_decorators, { kind: "accessor", name: "disableGit", static: false, private: false, access: { has: obj => "disableGit" in obj, get: obj => obj.disableGit, set: (obj, value) => { obj.disableGit = value; } }, metadata: _metadata }, _disableGit_initializers, _disableGit_extraInitializers);
             __esDecorate(this, null, _sourceLinkTemplate_decorators, { kind: "accessor", name: "sourceLinkTemplate", static: false, private: false, access: { has: obj => "sourceLinkTemplate" in obj, get: obj => obj.sourceLinkTemplate, set: (obj, value) => { obj.sourceLinkTemplate = value; } }, metadata: _metadata }, _sourceLinkTemplate_initializers, _sourceLinkTemplate_extraInitializers);
-            __esDecorate(this, null, _basePath_decorators, { kind: "accessor", name: "basePath", static: false, private: false, access: { has: obj => "basePath" in obj, get: obj => obj.basePath, set: (obj, value) => { obj.basePath = value; } }, metadata: _metadata }, _basePath_initializers, _basePath_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         #disableSources_accessor_storage = __runInitializers(this, _disableSources_initializers, void 0);
@@ -97,13 +92,13 @@ let SourcePlugin = (() => {
         #sourceLinkTemplate_accessor_storage = (__runInitializers(this, _disableGit_extraInitializers), __runInitializers(this, _sourceLinkTemplate_initializers, void 0));
         get sourceLinkTemplate() { return this.#sourceLinkTemplate_accessor_storage; }
         set sourceLinkTemplate(value) { this.#sourceLinkTemplate_accessor_storage = value; }
-        #basePath_accessor_storage = (__runInitializers(this, _sourceLinkTemplate_extraInitializers), __runInitializers(this, _basePath_initializers, void 0));
-        get basePath() { return this.#basePath_accessor_storage; }
-        set basePath(value) { this.#basePath_accessor_storage = value; }
+        get displayBasePath() {
+            return this.application.options.getValue("displayBasePath") || this.application.options.getValue("basePath");
+        }
         /**
          * All file names to find the base path from.
          */
-        fileNames = (__runInitializers(this, _basePath_extraInitializers), new Set());
+        fileNames = (__runInitializers(this, _sourceLinkTemplate_extraInitializers), new Set());
         repositories;
         constructor(owner) {
             super(owner);
@@ -170,7 +165,7 @@ let SourcePlugin = (() => {
                 !this.gitRevision) {
                 this.application.logger.warn(i18n.disable_git_set_and_git_revision_used());
             }
-            const basePath = this.basePath || getCommonDirectory([...this.fileNames]);
+            const basePath = this.displayBasePath || getCommonDirectory([...this.fileNames]);
             this.repositories ||= new RepositoryManager(basePath, this.gitRevision, this.gitRemote, this.sourceLinkTemplate, this.disableGit, this.application.logger);
             for (const id in context.project.reflections) {
                 const refl = context.project.reflections[id];

package/dist/lib/converter/symbols.js

@@ -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

@@ -410,7 +410,7 @@ const queryConverter = {
         if (!querySymbol) {
             // This can happen if someone uses `typeof` on some property
             // on a variable typed as `any` with a name that doesn't exist.
-            return new QueryType(ReferenceType.createBrokenReference(node.exprName.getText(), context.project));
+            return new QueryType(ReferenceType.createBrokenReference(node.exprName.getText(), context.project, undefined));
         }
         const ref = context.createSymbolReference(context.resolveAliasedSymbol(querySymbol), context, node.exprName.getText());
         ref.preferValues = true;
@@ -454,7 +454,7 @@ const referenceConverter = {
         if (!symbol) {
             // This happens when we get a reference to a type parameter
             // created within a mapped type, `K` in: `{ [K in T]: string }`
-            const ref = ReferenceType.createBrokenReference(context.checker.typeToString(type), context.project);
+            const ref = ReferenceType.createBrokenReference(context.checker.typeToString(type), context.project, undefined);
             ref.refersToTypeParameter = true;
             return ref;
         }
@@ -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/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",

package/dist/lib/internationalization/locales/de.d.cts

@@ -150,7 +150,6 @@ declare const _default: {
     help_excludeNotDocumentedKinds: string;
     help_excludeInternal: string;
     help_excludeCategories: string;
-    help_excludePrivate: string;
     help_excludeProtected: string;
     help_excludeReferences: string;
     help_externalSymbolLinkMappings: string;

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

@@ -45,6 +45,7 @@ module.exports = {
     at_most_one_inheritdoc_tag_expected_in_comment_at_0: "At most one @inheritDoc tag is expected in a comment, ignoring all but the first in comment at {0}",
     content_in_summary_overwritten_by_inheritdoc_in_comment_at_0: "Content in the summary section will be overwritten by the @inheritDoc tag in comment at {0}",
     content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @remarks block will be overwritten by the @inheritDoc tag in comment at {0}",
+    content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @returns block will be overwritten by the @inheritDoc tag in comment at {0}",
     example_tag_literal_name: "The first line of an example tag will be taken literally as the example name, and should only contain text",
     inheritdoc_tag_properly_capitalized: "The @inheritDoc tag should be properly capitalized",
     treating_unrecognized_tag_0_as_modifier: `Treating unrecognized tag {0} as a modifier tag`,
@@ -167,7 +168,8 @@ module.exports = {
     help_excludeNotDocumentedKinds: "Specify the type of reflections that can be removed by excludeNotDocumented",
     help_excludeInternal: "Prevent symbols that are marked with @internal from being documented",
     help_excludeCategories: "Exclude symbols within this category from the documentation",
-    help_excludePrivate: "Ignore private variables and methods, defaults to true.",
+    help_excludePrivate: "Ignore members marked with the private keyword and #private class fields, defaults to true.",
+    help_excludePrivateClassFields: "Ignore #private class fields, defaults to true.",
     help_excludeProtected: "Ignore protected variables and methods",
     help_excludeReferences: "If a symbol is exported multiple times, ignore all but the first export",
     help_externalSymbolLinkMappings: "Define custom links for symbols not included in the documentation",
@@ -195,11 +197,13 @@ module.exports = {
     help_gitRevision: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files. Has no effect if disableSources is set",
     help_gitRemote: "Use the specified remote for linking to GitHub/Bitbucket source files. Has no effect if disableGit or disableSources is set",
     help_disableGit: "Assume that all can be linked to with the sourceLinkTemplate, sourceLinkTemplate must be set if this is enabled. {path} will be rooted at basePath",
-    help_basePath: "Specifies the base path to be used when displaying file paths",
+    help_displayBasePath: "Specifies the base path to be used when displaying file paths. If not specified, basePath is used.",
     help_excludeTags: "Remove the listed block/modifier tags from doc comments",
     help_notRenderedTags: "Tags which will be preserved in doc comments, but not rendered when creating output",
     help_cascadedModifierTags: "Modifier tags which should be copied to all children of the parent reflection",
+    help_preservedTypeAnnotationTags: "Block tags whose type annotations should be preserved in the output.",
     help_readme: "Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page and start the documentation on the globals page",
+    help_basePath: "Specifies a path which links may be resolved relative to.",
     help_cname: "Set the CNAME file text, it's useful for custom domains on GitHub Pages",
     help_favicon: "Path to favicon to include as the site icon",
     help_sourceLinkExternal: "Specifies that source links should be treated as external links to be opened in a new tab",

package/dist/lib/internationalization/locales/en.d.cts

@@ -41,6 +41,7 @@ declare const _default: {
     readonly at_most_one_inheritdoc_tag_expected_in_comment_at_0: "At most one @inheritDoc tag is expected in a comment, ignoring all but the first in comment at {0}";
     readonly content_in_summary_overwritten_by_inheritdoc_in_comment_at_0: "Content in the summary section will be overwritten by the @inheritDoc tag in comment at {0}";
     readonly content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @remarks block will be overwritten by the @inheritDoc tag in comment at {0}";
+    readonly content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @returns block will be overwritten by the @inheritDoc tag in comment at {0}";
     readonly example_tag_literal_name: "The first line of an example tag will be taken literally as the example name, and should only contain text";
     readonly inheritdoc_tag_properly_capitalized: "The @inheritDoc tag should be properly capitalized";
     readonly treating_unrecognized_tag_0_as_modifier: "Treating unrecognized tag {0} as a modifier tag";
@@ -154,7 +155,8 @@ declare const _default: {
     readonly help_excludeNotDocumentedKinds: "Specify the type of reflections that can be removed by excludeNotDocumented";
     readonly help_excludeInternal: "Prevent symbols that are marked with @internal from being documented";
     readonly help_excludeCategories: "Exclude symbols within this category from the documentation";
-    readonly help_excludePrivate: "Ignore private variables and methods, defaults to true.";
+    readonly help_excludePrivate: "Ignore members marked with the private keyword and #private class fields, defaults to true.";
+    readonly help_excludePrivateClassFields: "Ignore #private class fields, defaults to true.";
     readonly help_excludeProtected: "Ignore protected variables and methods";
     readonly help_excludeReferences: "If a symbol is exported multiple times, ignore all but the first export";
     readonly help_externalSymbolLinkMappings: "Define custom links for symbols not included in the documentation";
@@ -182,11 +184,13 @@ declare const _default: {
     readonly help_gitRevision: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files. Has no effect if disableSources is set";
     readonly help_gitRemote: "Use the specified remote for linking to GitHub/Bitbucket source files. Has no effect if disableGit or disableSources is set";
     readonly help_disableGit: "Assume that all can be linked to with the sourceLinkTemplate, sourceLinkTemplate must be set if this is enabled. {path} will be rooted at basePath";
-    readonly help_basePath: "Specifies the base path to be used when displaying file paths";
+    readonly help_displayBasePath: "Specifies the base path to be used when displaying file paths. If not specified, basePath is used.";
     readonly help_excludeTags: "Remove the listed block/modifier tags from doc comments";
     readonly help_notRenderedTags: "Tags which will be preserved in doc comments, but not rendered when creating output";
     readonly help_cascadedModifierTags: "Modifier tags which should be copied to all children of the parent reflection";
+    readonly help_preservedTypeAnnotationTags: "Block tags whose type annotations should be preserved in the output.";
     readonly help_readme: "Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page and start the documentation on the globals page";
+    readonly help_basePath: "Specifies a path which links may be resolved relative to.";
     readonly help_cname: "Set the CNAME file text, it's useful for custom domains on GitHub Pages";
     readonly help_favicon: "Path to favicon to include as the site icon";
     readonly help_sourceLinkExternal: "Specifies that source links should be treated as external links to be opened in a new tab";

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

@@ -129,7 +129,6 @@ module.exports = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "excludeNotDocumented によって削除できる反射の種類を指定します",
     help_excludeInternal: "@internal でマークされたシンボルがドキュメント化されないようにする",
     help_excludeCategories: "このカテゴリ内のシンボルをドキュメントから除外する",
-    help_excludePrivate: "プライベート変数とメソッドを無視します。デフォルトは true です。",
     help_excludeProtected: "保護された変数とメソッドを無視する",
     help_excludeReferences: "シンボルが複数回エクスポートされた場合、最初のエクスポート以外はすべて無視されます。",
     help_externalSymbolLinkMappings: "ドキュメントに含まれていないシンボルのカスタムリンクを定義する",

package/dist/lib/internationalization/locales/ja.d.cts

@@ -119,7 +119,6 @@ declare const _default: {
     help_excludeNotDocumentedKinds: string;
     help_excludeInternal: string;
     help_excludeCategories: string;
-    help_excludePrivate: string;
     help_excludeProtected: string;
     help_excludeReferences: string;
     help_externalSymbolLinkMappings: string;

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

@@ -47,7 +47,6 @@ module.exports = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "excludeNotDocumented로 제거될 리플렉션 유형을 지정합니다",
     help_excludeInternal: "@internal로 표시된 심볼이 문서화되지 않도록 방지합니다",
     help_excludeCategories: "문서에서 제외할 카테고리 내의 심볼을 제외합니다",
-    help_excludePrivate: "비공개 변수와 메서드를 무시합니다. 기본값은 true입니다.",
     help_excludeProtected: "보호된 변수와 메서드를 무시합니다",
     help_excludeReferences: "심볼이 여러 번 내보내진 경우 첫 번째 내보내기를 제외하고 모두 무시합니다",
     help_externalSymbolLinkMappings: "문서에 포함되지 않은 심볼에 대한 사용자 정의 링크를 정의합니다",

package/dist/lib/internationalization/locales/ko.d.cts

@@ -39,7 +39,6 @@ declare const _default: {
     help_excludeNotDocumentedKinds: string;
     help_excludeInternal: string;
     help_excludeCategories: string;
-    help_excludePrivate: string;
     help_excludeProtected: string;
     help_excludeReferences: string;
     help_externalSymbolLinkMappings: string;

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

@@ -167,7 +167,6 @@ module.exports = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "指定可以通过 excludeNotDocumented 删除的反射类型",
     help_excludeInternal: "防止标有 @internal 的符号被记录",
     help_excludeCategories: "从文档中排除此类别中的符号",
-    help_excludePrivate: "忽略私有变量和方法，默认为 true。",
     help_excludeProtected: "忽略受保护的变量和方法",
     help_excludeReferences: "如果一个符号被导出多次，则忽略除第一次导出之外的所有导出",
     help_externalSymbolLinkMappings: "为文档中未包含的符号定义自定义链接",

package/dist/lib/internationalization/locales/zh.d.cts

@@ -152,7 +152,6 @@ declare const _default: {
     help_excludeNotDocumentedKinds: string;
     help_excludeInternal: string;
     help_excludeCategories: string;
-    help_excludePrivate: string;
     help_excludeProtected: string;
     help_excludeReferences: string;
     help_externalSymbolLinkMappings: string;

package/dist/lib/models/Comment.d.ts

@@ -85,6 +85,11 @@ export declare class CommentTag {
      * If this tag is one of those, it will be parsed out and included here.
      */
     name?: string;
+    /**
+     * Optional type annotation associated with this tag. TypeDoc will remove type annotations unless explicitly
+     * requested by the user with the `preservedTypeAnnotationTags` option.
+     */
+    typeAnnotation?: string;
     /**
      * The actual body text of this tag.
      */

package/dist/lib/models/Comment.js

@@ -50,6 +50,11 @@ export class CommentTag {
      * If this tag is one of those, it will be parsed out and included here.
      */
     name;
+    /**
+     * Optional type annotation associated with this tag. TypeDoc will remove type annotations unless explicitly
+     * requested by the user with the `preservedTypeAnnotationTags` option.
+     */
+    typeAnnotation;
     /**
      * The actual body text of this tag.
      */
@@ -83,6 +88,9 @@ export class CommentTag {
         if (this.name) {
             tag.name = this.name;
         }
+        if (this.typeAnnotation) {
+            tag.typeAnnotation = this.typeAnnotation;
+        }
         return tag;
     }
     toObject() {
@@ -90,11 +98,13 @@ export class CommentTag {
             tag: this.tag,
             name: this.name,
             content: Comment.serializeDisplayParts(this.content),
+            typeAnnotation: this.typeAnnotation,
         };
     }
     fromObject(de, obj) {
         // tag already set by Comment.fromObject
         this.name = obj.name;
+        this.typeAnnotation = obj.typeAnnotation;
         this.content = Comment.deserializeDisplayParts(de, obj.content);
     }
 }

package/dist/lib/models/types.d.ts

@@ -393,7 +393,7 @@ export declare class ReferenceType extends Type {
      * later during conversion.
      * @internal
      */
-    static createBrokenReference(name: string, project: ProjectReflection): ReferenceType;
+    static createBrokenReference(name: string, project: ProjectReflection, packageName: string | undefined): ReferenceType;
     protected getTypeString(): string;
     needsParenthesis(): boolean;
     toObject(serializer: Serializer): JSONOutput.ReferenceType;

package/dist/lib/models/types.js

@@ -833,8 +833,10 @@ let ReferenceType = (() => {
          * later during conversion.
          * @internal
          */
-        static createBrokenReference(name, project) {
-            return new ReferenceType(name, -1, project, name);
+        static createBrokenReference(name, project, packageName) {
+            const ref = new ReferenceType(name, -1, project, name);
+            ref.package = packageName;
+            return ref;
         }
         getTypeString() {
             const name = this.reflection ? this.reflection.name : this.name;

package/dist/lib/output/themes/MarkedPlugin.js

@@ -387,10 +387,17 @@ let MarkedPlugin = (() => {
 })();
 export { MarkedPlugin };
 function getTokenTextContent(token) {
+    // If there are children, we want their text content, not the full text content
     if (token.children) {
         return token.children.map(getTokenTextContent).join("");
     }
-    return token.content;
+    // If this is a simple text fragment, use its content
+    if (token.type === "text") {
+        return token.content;
+    }
+    // Otherwise this is some type of metadata token (e.g. header_open)
+    // or a HTML tag token. Don't include it in the text content.
+    return "";
 }
 const kindNames = ["note", "tip", "important", "warning", "caution"];
 const iconNames = ["alertNote", "alertTip", "alertImportant", "alertWarning", "alertCaution"];

package/dist/lib/output/themes/default/Slugger.d.ts

@@ -1,4 +1,4 @@
-import type { TypeDocOptionMap } from "../../../utils/index.js";
+import type { TypeDocOptionMap } from "#node-utils";
 /**
  * Responsible for getting a unique anchor for elements within a page.
  */

package/dist/lib/output/themes/default/Slugger.js

@@ -6,15 +6,23 @@ export class Slugger {
     options;
     seen = new Map();
     serialize(value) {
-        // Notes:
-        // There are quite a few trade-offs here.
+        // There are quite a few trade-offs here. We used to remove HTML tags here,
+        // but TypeDoc now removes the HTML tags before passing text into the slug
+        // method, which allows us to skip doing that here. This improves the slugger
+        // generation for headers which look like the following:
+        // (html allowed in markdown)
+        // # test <t>
+        // (html disallowed in markdown)
+        // # test <t>
+        // both of the above should slug to test-t
         return (value
             .trim()
-            // remove html tags
-            .replace(/<[!/a-z].*?>/gi, "")
             // remove unwanted chars
             .replace(/[\u2000-\u206F\u2E00-\u2E7F\\'!"#$%&()*+,./:;<=>?@[\]^`{|}~]/g, "")
-            .replace(/\s/g, "-"));
+            // change whitespace to dash
+            .replace(/\s/g, "-")
+            // combine adjacent dashes
+            .replace(/--+/, "-"));
     }
     constructor(options) {
         this.options = options;

package/dist/lib/output/themes/default/partials/comment.js

@@ -58,6 +58,7 @@ export function commentTags(context, props) {
                 JSX.createElement("h4", { class: "tsd-anchor-link", id: anchor },
                     name,
                     anchorIcon(context, anchor)),
+                item.typeAnnotation && JSX.createElement("span", { class: "tsd-type-annotation" }, item.typeAnnotation),
                 JSX.createElement(JSX.Raw, { html: context.markdown(item.content) }))));
     });
     return (JSX.createElement(JSX.Fragment, null,

package/dist/lib/output/themes/default/partials/typeAndParent.d.ts

@@ -1,4 +1,4 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext.js";
-import { type Type } from "../../../../models/index.js";
+import { type Type } from "#models";
 import { JSX } from "#utils";
 export declare const typeAndParent: (context: DefaultThemeRenderContext, props: Type) => JSX.Element;

package/dist/lib/output/themes/default/partials/typeAndParent.js

@@ -1,4 +1,4 @@
-import { ArrayType, ReferenceType, SignatureReflection } from "../../../../models/index.js";
+import { ArrayType, ReferenceType, SignatureReflection } from "#models";
 import { JSX } from "#utils";
 export const typeAndParent = (context, props) => {
     if (props instanceof ArrayType) {
@@ -6,13 +6,23 @@ export const typeAndParent = (context, props) => {
             context.typeAndParent(props.elementType),
             "[]"));
     }
-    if (props instanceof ReferenceType && props.reflection) {
-        const refl = props.reflection instanceof SignatureReflection ? props.reflection.parent : props.reflection;
-        const parent = refl.parent;
-        return (JSX.createElement(JSX.Fragment, null,
-            JSX.createElement("a", { href: context.urlTo(parent) }, parent.name),
-            ".",
-            JSX.createElement("a", { href: context.urlTo(refl) }, refl.name)));
+    if (props instanceof ReferenceType) {
+        if (props.reflection) {
+            const refl = props.reflection instanceof SignatureReflection ? props.reflection.parent : props.reflection;
+            const parent = refl.parent;
+            return (JSX.createElement(JSX.Fragment, null,
+                JSX.createElement("a", { href: context.urlTo(parent) }, parent.name),
+                ".",
+                JSX.createElement("a", { href: context.urlTo(refl) }, refl.name)));
+        }
+        else if (props.externalUrl) {
+            if (props.externalUrl === "#") {
+                return JSX.createElement(JSX.Fragment, null, props.toString());
+            }
+            else {
+                return JSX.createElement("a", { href: props.externalUrl, class: "external", target: "_blank" }, props.name);
+            }
+        }
     }
     return JSX.createElement(JSX.Fragment, null, props.toString());
 };

package/dist/lib/serialization/schema.d.ts

@@ -226,7 +226,7 @@ export interface Comment extends Partial<S<M.Comment, "blockTags" | "label">> {
     modifierTags?: TagString[];
 }
 /** @category Comments */
-export interface CommentTag extends S<M.CommentTag, "tag" | "name"> {
+export interface CommentTag extends S<M.CommentTag, "tag" | "name" | "typeAnnotation"> {
     content: CommentDisplayPart[];
 }
 /**

package/dist/lib/utils/ValidatingFileRegistry.d.ts

@@ -2,6 +2,8 @@ import { type FileId, FileRegistry } from "../models/FileRegistry.js";
 import type { Deserializer, JSONOutput } from "#serialization";
 import { type NormalizedPath } from "#utils";
 export declare class ValidatingFileRegistry extends FileRegistry {
+    basePath: NormalizedPath;
+    constructor(basePath?: NormalizedPath);
     register(sourcePath: NormalizedPath, relativePath: NormalizedPath): {
         target: FileId;
         anchor: string | undefined;

package/dist/lib/utils/ValidatingFileRegistry.js

@@ -2,14 +2,29 @@ import { FileRegistry } from "../models/FileRegistry.js";
 import { i18n, NormalizedPathUtils } from "#utils";
 import { existsSync } from "fs";
 export class ValidatingFileRegistry extends FileRegistry {
+    basePath;
+    constructor(basePath = "") {
+        super();
+        this.basePath = basePath;
+    }
     register(sourcePath, relativePath) {
-        const absolute = NormalizedPathUtils.resolve(NormalizedPathUtils.dirname(sourcePath), relativePath);
-        const absoluteWithoutAnchor = absolute.replace(/#.*/, "");
+        let absolute = NormalizedPathUtils.resolve(NormalizedPathUtils.dirname(sourcePath), relativePath);
+        let absoluteWithoutAnchor = absolute.replace(/#.*/, "");
         // Note: We allow paths to directories to be registered here, but the AssetsPlugin will not
         // copy them to the output path. This is so that we can link to directories and associate them
         // with reflections in packages mode.
         if (!existsSync(absoluteWithoutAnchor)) {
-            return;
+            // If the relative path didn't exist normally, also check the path relative to the assetBasePath option
+            if (this.basePath != "") {
+                absolute = NormalizedPathUtils.resolve(this.basePath, relativePath);
+                absoluteWithoutAnchor = absolute.replace(/#.*/, "");
+                if (!existsSync(absoluteWithoutAnchor)) {
+                    return;
+                }
+            }
+            else {
+                return;
+            }
         }
         return this.registerAbsolute(absolute);
     }

package/dist/lib/utils/entry-point.js

@@ -124,7 +124,7 @@ export function getDocumentEntryPoints(logger, options) {
     // that have at some point or another been used for markdown: https://superuser.com/a/285878
     const supportedFileRegex = /\.(md|markdown)$/;
     const expanded = expandInputFiles(logger, docPaths, options, supportedFileRegex);
-    const baseDir = options.getValue("basePath") || getCommonDirectory(expanded);
+    const baseDir = options.getValue("displayBasePath") || options.getValue("basePath") || getCommonDirectory(expanded);
     return expanded.map((path) => {
         return {
             displayName: relative(baseDir, path).replace(/\.[^.]+$/, ""),
@@ -184,7 +184,8 @@ function getModuleName(fileName, baseDir) {
  * This is in contrast with the package-oriented `getEntryPointsForPackages`
  */
 function getEntryPointsForPaths(logger, inputFiles, options, programs = getEntryPrograms(inputFiles, logger, options)) {
-    const baseDir = options.getValue("basePath") || getCommonDirectory(inputFiles);
+    const baseDir = options.getValue("displayBasePath") || options.getValue("basePath") ||
+        getCommonDirectory(inputFiles);
     const entryPoints = [];
     let expandSuggestion = true;
     entryLoop: for (const fileOrDir of inputFiles.map(normalizePath)) {

package/dist/lib/utils/options/declaration.d.ts

@@ -93,6 +93,7 @@ export interface TypeDocOptionMap {
     excludeNotDocumented: boolean;
     excludeNotDocumentedKinds: ReflectionKind.KindString[];
     excludeInternal: boolean;
+    excludePrivateClassFields: boolean;
     excludePrivate: boolean;
     excludeProtected: boolean;
     excludeReferences: boolean;
@@ -108,6 +109,7 @@ export interface TypeDocOptionMap {
     gitRevision: string;
     gitRemote: string;
     readme: string;
+    basePath: NormalizedPath;
     outputs: ManuallyValidatedOption<Array<OutputSpecification>>;
     out: NormalizedPath;
     html: NormalizedPath;
@@ -145,7 +147,7 @@ export interface TypeDocOptionMap {
      * strictly typed here.
      */
     markdownItLoader: ManuallyValidatedOption<(parser: any) => void>;
-    basePath: NormalizedPath;
+    displayBasePath: NormalizedPath;
     cname: string;
     favicon: NormalizedPath;
     githubPages: boolean;
@@ -199,6 +201,7 @@ export interface TypeDocOptionMap {
     notRenderedTags: TagString[];
     externalSymbolLinkMappings: ManuallyValidatedOption<Record<string, Record<string, string>>>;
     cascadedModifierTags: TagString[];
+    preservedTypeAnnotationTags: TagString[];
     categorizeByGroup: boolean;
     groupReferencesByType: boolean;
     defaultCategory: string;

package/dist/lib/utils/options/defaults.d.ts

@@ -11,6 +11,7 @@ export declare const blockTags: readonly TagString[];
 export declare const inlineTags: readonly TagString[];
 export declare const modifierTags: readonly TagString[];
 export declare const cascadedModifierTags: readonly TagString[];
+export declare const preservedTypeAnnotationTags: readonly TagString[];
 export declare const notRenderedTags: readonly TagString[];
 export declare const highlightLanguages: readonly BundledLanguage[];
 export declare const ignoredHighlightLanguages: readonly string[];

package/dist/lib/utils/options/defaults.js

@@ -37,6 +37,7 @@ export const cascadedModifierTags = [
     "@beta",
     "@experimental",
 ];
+export const preservedTypeAnnotationTags = [];
 export const notRenderedTags = [
     "@showCategories",
     "@showGroups",

package/dist/lib/utils/options/sources/typedoc.js

@@ -16,9 +16,7 @@ function makeTagArrayValidator(name) {
 }
 // For convenience, added in the same order as they are documented on the website.
 export function addTypeDocOptions(options) {
-    ///////////////////////////
-    // Configuration Options //
-    ///////////////////////////
+    // MARK: Configuration Options
     options.addDeclaration({
         type: ParameterType.Path,
         name: "options",
@@ -84,9 +82,7 @@ export function addTypeDocOptions(options) {
             }
         },
     });
-    ///////////////////////////
-    ////// Input Options //////
-    ///////////////////////////
+    // MARK: Input Options
     options.addDeclaration({
         name: "entryPoints",
         help: () => i18n.help_entryPoints(),
@@ -171,6 +167,12 @@ export function addTypeDocOptions(options) {
         type: ParameterType.Boolean,
         defaultValue: true,
     });
+    options.addDeclaration({
+        name: "excludePrivateClassFields",
+        help: () => i18n.help_excludePrivateClassFields(),
+        type: ParameterType.Boolean,
+        defaultValue: true,
+    });
     options.addDeclaration({
         name: "excludeProtected",
         help: () => i18n.help_excludeProtected(),
@@ -202,9 +204,17 @@ export function addTypeDocOptions(options) {
             }
         },
     });
-    ///////////////////////////
-    ///// Output Options //////
-    ///////////////////////////
+    options.addDeclaration({
+        name: "readme",
+        help: () => i18n.help_readme(),
+        type: ParameterType.Path,
+    });
+    options.addDeclaration({
+        name: "basePath",
+        help: () => i18n.help_basePath(),
+        type: ParameterType.Path,
+    });
+    // MARK: Output Options
     options.addDeclaration({
         name: "outputs",
         help: () => i18n.help_out(),
@@ -396,13 +406,8 @@ export function addTypeDocOptions(options) {
         type: ParameterType.Boolean,
     });
     options.addDeclaration({
-        name: "basePath",
-        help: () => i18n.help_basePath(),
-        type: ParameterType.Path,
-    });
-    options.addDeclaration({
-        name: "readme",
-        help: () => i18n.help_readme(),
+        name: "displayBasePath",
+        help: () => i18n.help_displayBasePath(),
         type: ParameterType.Path,
     });
     options.addDeclaration({
@@ -622,9 +627,7 @@ export function addTypeDocOptions(options) {
         help: () => i18n.help_useFirstParagraphOfCommentAsSummary(),
         type: ParameterType.Boolean,
     });
-    ///////////////////////////
-    ///// Comment Options /////
-    ///////////////////////////
+    // MARK: Comment Options
     options.addDeclaration({
         name: "jsDocCompatibility",
         help: () => i18n.help_jsDocCompatibility(),
@@ -703,9 +706,14 @@ export function addTypeDocOptions(options) {
         defaultValue: OptionDefaults.cascadedModifierTags,
         validate: makeTagArrayValidator("cascadedModifierTags"),
     });
-    ///////////////////////////
-    // Organization Options ///
-    ///////////////////////////
+    options.addDeclaration({
+        name: "preservedTypeAnnotationTags",
+        help: () => i18n.help_preservedTypeAnnotationTags(),
+        type: ParameterType.Array,
+        defaultValue: OptionDefaults.preservedTypeAnnotationTags,
+        validate: makeTagArrayValidator("preservedTypeAnnotationTags"),
+    });
+    // MARK: Organization Options
     options.addDeclaration({
         name: "categorizeByGroup",
         help: () => i18n.help_categorizeByGroup(),
@@ -764,9 +772,7 @@ export function addTypeDocOptions(options) {
             }
         },
     });
-    ///////////////////////////
-    ///// General Options /////
-    ///////////////////////////
+    // MARK: General Options
     options.addDeclaration({
         name: "watch",
         help: () => i18n.help_watch(),

package/dist/lib/utils/options/tsdoc-defaults.d.ts

@@ -1,5 +1,5 @@
 export declare const tsdocBlockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam"];
-export declare const blockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam", "@author", "@callback", "@category", "@categoryDescription", "@default", "@document", "@extends", "@augments", "@yields", "@group", "@groupDescription", "@import", "@inheritDoc", "@jsx", "@license", "@module", "@mergeModuleWith", "@prop", "@property", "@return", "@satisfies", "@since", "@sortStrategy", "@template", "@type", "@typedef", "@summary", "@preventInline", "@inlineType", "@preventExpand", "@expandType"];
+export declare const blockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam", "@author", "@callback", "@category", "@categoryDescription", "@default", "@document", "@extends", "@augments", "@yields", "@group", "@groupDescription", "@import", "@inheritDoc", "@jsx", "@license", "@module", "@mergeModuleWith", "@prop", "@property", "@return", "@satisfies", "@since", "@sortStrategy", "@template", "@this", "@type", "@typedef", "@summary", "@preventInline", "@inlineType", "@preventExpand", "@expandType"];
 export declare const tsdocInlineTags: readonly ["@link", "@inheritDoc", "@label"];
 export declare const inlineTags: readonly ["@link", "@inheritDoc", "@label", "@linkcode", "@linkplain", "@include", "@includeCode"];
 export declare const tsdocModifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@public", "@readonly", "@sealed", "@virtual"];

package/dist/lib/utils/options/tsdoc-defaults.js

@@ -37,6 +37,7 @@ export const blockTags = [
     "@since",
     "@sortStrategy",
     "@template", // Alias for @typeParam
+    "@this",
     "@type",
     "@typedef",
     "@summary",

package/dist/lib/utils-common/general.js

@@ -6,6 +6,8 @@ export function assertNever(x) {
 }
 export function assert(x, message = "Assertion failed") {
     if (!x) {
+        // eslint-disable-next-line no-debugger
+        debugger;
         throw new Error(message);
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.28.12",
+  "version": "0.28.14",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {
@@ -111,9 +111,9 @@
     "test": "mocha --config .config/mocha.fast.json",
     "test:cov": "c8 -r lcov mocha --config .config/mocha.fast.json",
     "doc:c": "node bin/typedoc --tsconfig src/test/converter/tsconfig.json",
-    "doc:cd": "node --inspect-brk bin/typedoc --tsconfig src/test/converter/tsconfig.json",
+    "doc:cd": "node --inspect-brk dist/lib/cli.js --tsconfig src/test/converter/tsconfig.json",
     "doc:c2": "node bin/typedoc --options src/test/converter2 --tsconfig src/test/converter2/tsconfig.json",
-    "doc:c2d": "node --inspect-brk bin/typedoc --options src/test/converter2 --tsconfig src/test/converter2/tsconfig.json",
+    "doc:c2d": "node --inspect-brk dist/lib/cli.js --options src/test/converter2 --tsconfig src/test/converter2/tsconfig.json",
     "example": "cd example && node ../bin/typedoc",
     "test:full": "c8 -r lcov -r text-summary mocha --config .config/mocha.full.json",
     "rebuild_specs": "node scripts/rebuild_specs.js",

package/tsdoc.json

@@ -146,6 +146,11 @@
             "syntaxKind": "block",
             "allowMultiple": true
         },
+        {
+            "tagName": "@this",
+            "syntaxKind": "block",
+            "allowMultiple": false
+        },
         {
             "tagName": "@linkcode",
             "syntaxKind": "inline",