typedoc 0.28.13 → 0.28.14

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

@@ -222,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/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

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

@@ -168,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",
@@ -200,6 +201,7 @@ module.exports = {
     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",

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

@@ -155,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";
@@ -187,6 +188,7 @@ declare const _default: {
     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";

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/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/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/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;
@@ -200,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

@@ -167,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(),
@@ -700,6 +706,13 @@ export function addTypeDocOptions(options) {
         defaultValue: OptionDefaults.cascadedModifierTags,
         validate: makeTagArrayValidator("cascadedModifierTags"),
     });
+    options.addDeclaration({
+        name: "preservedTypeAnnotationTags",
+        help: () => i18n.help_preservedTypeAnnotationTags(),
+        type: ParameterType.Array,
+        defaultValue: OptionDefaults.preservedTypeAnnotationTags,
+        validate: makeTagArrayValidator("preservedTypeAnnotationTags"),
+    });
     // MARK: Organization Options
     options.addDeclaration({
         name: "categorizeByGroup",

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.13",
+  "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",