typedoc 0.26.0 → 0.26.2

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

@@ -1,5 +1,5 @@
 import type { Deserializer, Serializer } from "../serialization";
-import type { FileRegistry as JSONMediaRegistry } from "../serialization/schema";
+import type { FileRegistry as JSONFileRegistry } from "../serialization/schema";
 import type { Reflection } from "./reflections";
 export declare class FileRegistry {
     protected nextId: number;
@@ -17,10 +17,15 @@ export declare class FileRegistry {
     resolve(id: number): string | Reflection | undefined;
     getName(id: number): string | undefined;
     getNameToAbsoluteMap(): ReadonlyMap<string, string>;
-    toObject(ser: Serializer): JSONMediaRegistry;
-    fromObject(de: Deserializer, obj: JSONMediaRegistry): void;
+    toObject(ser: Serializer): JSONFileRegistry;
+    /**
+     * Revive a file registry from disc.
+     * Note that in the packages context this may be called multiple times on
+     * a single object, and should merge in files from the other registries.
+     */
+    fromObject(de: Deserializer, obj: JSONFileRegistry): void;
 }
 export declare class ValidatingFileRegistry extends FileRegistry {
     register(sourcePath: string, relativePath: string): number | undefined;
-    fromObject(de: Deserializer, obj: JSONMediaRegistry): void;
+    fromObject(de: Deserializer, obj: JSONFileRegistry): void;
 }

package/dist/lib/models/FileRegistry.js

@@ -7,7 +7,7 @@ const fs_1 = require("fs");
 class FileRegistry {
     constructor() {
         this.nextId = 1;
-        // The combination of thest two make up the registry
+        // The combination of these two make up the registry
         this.mediaToReflection = new Map();
         this.mediaToPath = new Map();
         this.reflectionToPath = new Map();
@@ -87,6 +87,11 @@ class FileRegistry {
         }
         return result;
     }
+    /**
+     * Revive a file registry from disc.
+     * Note that in the packages context this may be called multiple times on
+     * a single object, and should merge in files from the other registries.
+     */
     fromObject(de, obj) {
         for (const [key, val] of Object.entries(obj.entries)) {
             const absolute = (0, utils_1.normalizePath)((0, path_1.resolve)(de.projectRoot, val));

package/dist/lib/models/comments/comment.d.ts

@@ -123,8 +123,8 @@ export declare class Comment {
         kind: "inline-tag";
         tag: `@${string}`;
         text: string;
-        target?: string | Reflection | ReflectionSymbolId | undefined;
-        tsLinkText?: string | undefined;
+        target?: Reflection | string | ReflectionSymbolId;
+        tsLinkText?: string;
     } | {
         kind: "relative-link";
         /**
@@ -180,6 +180,13 @@ export declare class Comment {
      * @internal
      */
     discoveryId?: number;
+    /**
+     * If the comment was inherited from a different "parent" declaration
+     * (see #2545), then it is desirable to know this as any `@param` tags
+     * which do not apply should not cause warnings. This is not serialized,
+     * and only set when the comment was created from a `ts.CommentRange`.
+     */
+    inheritedFromParentDeclaration?: boolean;
     /**
      * Creates a new Comment instance.
      */

package/dist/lib/models/comments/comment.js

@@ -94,6 +94,9 @@ let Comment = (() => {
     let _discoveryId_decorators;
     let _discoveryId_initializers = [];
     let _discoveryId_extraInitializers = [];
+    let _inheritedFromParentDeclaration_decorators;
+    let _inheritedFromParentDeclaration_initializers = [];
+    let _inheritedFromParentDeclaration_extraInitializers = [];
     return _a = class Comment {
             /**
              * Debugging utility for combining parts into a simple string. Not suitable for
@@ -301,7 +304,14 @@ let Comment = (() => {
                  * @internal
                  */
                 this.discoveryId = (__runInitializers(this, _sourcePath_extraInitializers), __runInitializers(this, _discoveryId_initializers, void 0));
-                __runInitializers(this, _discoveryId_extraInitializers);
+                /**
+                 * If the comment was inherited from a different "parent" declaration
+                 * (see #2545), then it is desirable to know this as any `@param` tags
+                 * which do not apply should not cause warnings. This is not serialized,
+                 * and only set when the comment was created from a `ts.CommentRange`.
+                 */
+                this.inheritedFromParentDeclaration = (__runInitializers(this, _discoveryId_extraInitializers), __runInitializers(this, _inheritedFromParentDeclaration_initializers, void 0));
+                __runInitializers(this, _inheritedFromParentDeclaration_extraInitializers);
                 this.summary = summary;
                 this.blockTags = blockTags;
                 this.modifierTags = modifierTags;
@@ -314,6 +324,8 @@ let Comment = (() => {
                 const comment = new _a(_a.cloneDisplayParts(this.summary), this.blockTags.map((tag) => tag.clone()), new Set(this.modifierTags));
                 comment.discoveryId = this.discoveryId;
                 comment.sourcePath = this.sourcePath;
+                comment.inheritedFromParentDeclaration =
+                    this.inheritedFromParentDeclaration;
                 return comment;
             }
             /**
@@ -395,8 +407,10 @@ let Comment = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
             _sourcePath_decorators = [general_1.NonEnumerable];
             _discoveryId_decorators = [general_1.NonEnumerable];
+            _inheritedFromParentDeclaration_decorators = [general_1.NonEnumerable];
             __esDecorate(null, null, _sourcePath_decorators, { kind: "field", name: "sourcePath", static: false, private: false, access: { has: obj => "sourcePath" in obj, get: obj => obj.sourcePath, set: (obj, value) => { obj.sourcePath = value; } }, metadata: _metadata }, _sourcePath_initializers, _sourcePath_extraInitializers);
             __esDecorate(null, null, _discoveryId_decorators, { kind: "field", name: "discoveryId", static: false, private: false, access: { has: obj => "discoveryId" in obj, get: obj => obj.discoveryId, set: (obj, value) => { obj.discoveryId = value; } }, metadata: _metadata }, _discoveryId_initializers, _discoveryId_extraInitializers);
+            __esDecorate(null, null, _inheritedFromParentDeclaration_decorators, { kind: "field", name: "inheritedFromParentDeclaration", static: false, private: false, access: { has: obj => "inheritedFromParentDeclaration" in obj, get: obj => obj.inheritedFromParentDeclaration, set: (obj, value) => { obj.inheritedFromParentDeclaration = value; } }, metadata: _metadata }, _inheritedFromParentDeclaration_initializers, _inheritedFromParentDeclaration_extraInitializers);
             if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         })(),
         _a;

package/dist/lib/models/reflections/declaration.js

@@ -129,6 +129,7 @@ class DeclarationReflection extends container_1.ContainerReflection {
         if (obj.variant === "project") {
             this.kind = kind_1.ReflectionKind.Module;
             this.packageVersion = obj.packageVersion;
+            this.project.files.fromObject(de, obj.files || {});
             de.defer(() => {
                 for (const [id, sid] of Object.entries(obj.symbolIdMap || {})) {
                     const refl = this.project.getReflectionById(de.oldIdToNewId[+id] ?? -1);

package/dist/lib/models/reflections/project.js

@@ -296,7 +296,7 @@ class ProjectReflection extends container_1.ContainerReflection {
         if (obj.readme) {
             this.readme = comments_1.Comment.deserializeDisplayParts(de, obj.readme);
         }
-        this.files.fromObject(de, obj.files);
+        this.files.fromObject(de, obj.files || {});
         de.defer(() => {
             // Unnecessary conditional in release
             for (const [id, sid] of Object.entries(obj.symbolIdMap || {})) {

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

@@ -256,7 +256,7 @@ let MarkedPlugin = (() => {
             this.parser = (0, markdown_it_1.default)({
                 ...this.markdownItOptions,
                 highlight: (code, lang) => {
-                    code = (0, highlighter_1.highlight)(code, lang || "ts");
+                    code = this.getHighlighted(code, lang || "ts");
                     code = code.replace(/\n$/, "") + "\n";
                     if (!lang) {
                         return `<pre><code>${code}</code><button>${this.application.i18n.theme_copy()}</button></pre>\n`;

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

@@ -53,12 +53,12 @@ export declare class DefaultThemeRenderContext {
     memberGetterSetter: (props: DeclarationReflection) => import("../../../utils/jsx.elements").JsxElement;
     memberReference: (props: import("../../../models").ReferenceReflection) => import("../../../utils/jsx.elements").JsxElement;
     memberSignatureBody: (props: import("../../../models").SignatureReflection, r_1?: {
-        hideSources?: boolean | undefined;
+        hideSources?: boolean;
     } | undefined) => import("../../../utils/jsx.elements").JsxElement;
     memberSignatureTitle: (props: import("../../../models").SignatureReflection, r_1?: {
-        hideName?: boolean | undefined;
-        arrowStyle?: boolean | undefined;
-        hideParamTypes?: boolean | undefined;
+        hideName?: boolean;
+        arrowStyle?: boolean;
+        hideParamTypes?: boolean;
     } | undefined) => import("../../../utils/jsx.elements").JsxElement;
     memberSignatures: (props: DeclarationReflection) => import("../../../utils/jsx.elements").JsxElement;
     memberSources: (props: DeclarationReflection | import("../../../models").SignatureReflection) => import("../../../utils/jsx.elements").JsxElement;

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

@@ -1,3 +1,4 @@
+export declare const emptyArray: readonly [];
 /**
  * Inserts an item into an array sorted by priority. If two items have the same priority,
  * the item will be inserted later will be placed earlier in the array.
@@ -48,3 +49,5 @@ export declare function zip<T extends Iterable<any>[]>(...args: T): Iterable<{
     [K in keyof T]: T[K] extends Iterable<infer U> ? U : T[K];
 }>;
 export declare function filterMap<T, U>(iter: Iterable<T>, fn: (item: T) => U | undefined): U[];
+export declare function firstDefined<T, U>(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined;
+export declare function filter<T>(array: readonly T[] | undefined, predicate: (value: T, index: number, array: readonly T[]) => boolean): readonly T[];

package/dist/lib/utils/array.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyArray = void 0;
 exports.insertPrioritySorted = insertPrioritySorted;
 exports.insertOrderSorted = insertOrderSorted;
 exports.binaryFindPartition = binaryFindPartition;
@@ -9,6 +10,9 @@ exports.unique = unique;
 exports.partition = partition;
 exports.zip = zip;
 exports.filterMap = filterMap;
+exports.firstDefined = firstDefined;
+exports.filter = filter;
+exports.emptyArray = [];
 /**
  * Inserts an item into an array sorted by priority. If two items have the same priority,
  * the item will be inserted later will be placed earlier in the array.
@@ -123,3 +127,18 @@ function filterMap(iter, fn) {
     }
     return result;
 }
+function firstDefined(array, callback) {
+    if (array === undefined) {
+        return undefined;
+    }
+    for (let i = 0; i < array.length; i++) {
+        const result = callback(array[i], i);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    return undefined;
+}
+function filter(array, predicate) {
+    return array ? array.filter(predicate) : exports.emptyArray;
+}

package/dist/lib/utils/highlighter.js

@@ -133,7 +133,7 @@ async function loadHighlighter(lightTheme, darkTheme, langs) {
     if (highlighter)
         return;
     const shiki = await import("shiki");
-    const hl = await shiki.getHighlighter({ themes: [lightTheme, darkTheme], langs });
+    const hl = await shiki.createHighlighter({ themes: [lightTheme, darkTheme], langs });
     highlighter = new DoubleHighlighter(hl, lightTheme, darkTheme);
 }
 function isSupportedLanguage(lang) {
@@ -152,7 +152,7 @@ function getSupportedThemes() {
     return supportedThemes;
 }
 function isLoadedLanguage(lang) {
-    return highlighter?.supports(lang) ?? false;
+    return lang === "text" || (highlighter?.supports(lang) ?? false);
 }
 function highlight(code, lang) {
     (0, assert_1.ok)(highlighter, "Tried to highlight with an uninitialized highlighter");

package/dist/lib/utils/minimalSourceFile.js

@@ -18,7 +18,7 @@ class MinimalSourceFile {
         }
         const starts = lineStarts.get(this);
         while (pos >= starts[starts.length - 1]) {
-            const nextStart = this.text.indexOf("\n", starts[starts.length - 1] + 1);
+            const nextStart = this.text.indexOf("\n", starts[starts.length - 1]);
             if (nextStart === -1) {
                 starts.push(Infinity);
             }

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

@@ -155,6 +155,7 @@ export interface TypeDocOptionMap {
     useTsLinkResolution: boolean;
     preserveLinkText: boolean;
     jsDocCompatibility: JsDocCompatibility;
+    suppressCommentWarningsInDeclarationFiles: boolean;
     blockTags: `@${string}`[];
     inlineTags: `@${string}`[];
     modifierTags: `@${string}`[];

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

@@ -74,7 +74,7 @@ class Options {
     snapshot() {
         const key = {};
         optionSnapshots.set(key, {
-            values: JSON.stringify(this._values),
+            values: { ...this._values },
             set: new Set(this._setOptions),
         });
         return key;
@@ -85,7 +85,7 @@ class Options {
      */
     restore(snapshot) {
         const data = optionSnapshots.get(snapshot);
-        this._values = JSON.parse(data.values);
+        this._values = { ...data.values };
         this._setOptions = new Set(data.set);
     }
     reset(name) {
@@ -176,7 +176,7 @@ class Options {
             oldValue = (0, declaration_2.getDefaultValue)(declaration);
         const converted = (0, declaration_2.convert)(value, declaration, this._i18n, configPath ?? process.cwd(), oldValue);
         if (declaration.type === declaration_1.ParameterType.Flags) {
-            Object.assign(this._values[declaration.name], converted);
+            this._values[declaration.name] = Object.assign({}, this._values[declaration.name], converted);
         }
         else {
             this._values[declaration.name] = converted;

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

@@ -78,7 +78,7 @@ class TypeDocReader {
         }
         seen.add(file);
         let fileContent;
-        if (file.endsWith(".json")) {
+        if (file.endsWith(".json") || file.endsWith(".jsonc")) {
             const readResult = typescript_1.default.readConfigFile((0, paths_1.normalizePath)(file), (path) => FS.readFileSync(path, "utf-8"));
             if (readResult.error) {
                 logger.error(logger.i18n.failed_read_options_file_0((0, paths_1.nicePath)(file)));

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

@@ -610,6 +610,11 @@ function addTypeDocOptions(options) {
             ignoreUnescapedBraces: true,
         },
     });
+    options.addDeclaration({
+        name: "suppressCommentWarningsInDeclarationFiles",
+        help: (i18n) => i18n.help_lang(),
+        type: declaration_1.ParameterType.Boolean,
+    });
     options.addDeclaration({
         name: "commentStyle",
         help: (i18n) => i18n.help_commentStyle(),

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

@@ -1,6 +1,6 @@
 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", "@category", "@categoryDescription", "@default", "@document", "@group", "@groupDescription", "@inheritDoc", "@license", "@module", "@return", "@template", "@type", "@typedef", "@callback", "@prop", "@property", "@satisfies", "@import", "@jsx"];
+export declare const blockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam", "@author", "@callback", "@category", "@categoryDescription", "@default", "@document", "@group", "@groupDescription", "@import", "@inheritDoc", "@jsx", "@license", "@module", "@prop", "@property", "@return", "@satisfies", "@template", "@type", "@typedef"];
 export declare const tsdocInlineTags: readonly ["@link", "@inheritDoc", "@label"];
 export declare const inlineTags: readonly ["@link", "@inheritDoc", "@label", "@linkcode", "@linkplain"];
-export declare const tsdocModifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@private", "@protected", "@public", "@readonly", "@sealed", "@virtual"];
-export declare const modifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@private", "@protected", "@public", "@readonly", "@sealed", "@virtual", "@class", "@enum", "@event", "@hidden", "@hideCategories", "@hideGroups", "@ignore", "@interface", "@namespace", "@overload", "@showCategories", "@showGroups", "@hideconstructor"];
+export declare const tsdocModifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@public", "@readonly", "@sealed", "@virtual"];
+export declare const modifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@public", "@readonly", "@sealed", "@virtual", "@class", "@enum", "@event", "@hidden", "@hideCategories", "@hideconstructor", "@hideGroups", "@ignore", "@interface", "@namespace", "@overload", "@private", "@protected", "@showCategories", "@showGroups"];

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

@@ -16,27 +16,26 @@ exports.tsdocBlockTags = [
 ];
 exports.blockTags = [
     ...exports.tsdocBlockTags,
+    "@author",
+    "@callback",
     "@category",
     "@categoryDescription",
     "@default",
     "@document",
     "@group",
     "@groupDescription",
+    "@import",
     "@inheritDoc",
+    "@jsx",
     "@license",
     "@module",
-    "@return",
-    // Alias for @typeParam
-    "@template",
-    // Because TypeScript is important!
-    "@type",
-    "@typedef",
-    "@callback",
     "@prop",
     "@property",
+    "@return",
     "@satisfies",
-    "@import",
-    "@jsx",
+    "@template", // Alias for @typeParam
+    "@type", // Because TypeScript is important!
+    "@typedef",
 ];
 exports.tsdocInlineTags = ["@link", "@inheritDoc", "@label"];
 exports.inlineTags = [
@@ -52,8 +51,6 @@ exports.tsdocModifierTags = [
     "@internal",
     "@override",
     "@packageDocumentation",
-    "@private",
-    "@protected",
     "@public",
     "@readonly",
     "@sealed",
@@ -66,12 +63,14 @@ exports.modifierTags = [
     "@event",
     "@hidden",
     "@hideCategories",
+    "@hideconstructor",
     "@hideGroups",
     "@ignore",
     "@interface",
     "@namespace",
     "@overload",
+    "@private",
+    "@protected",
     "@showCategories",
     "@showGroups",
-    "@hideconstructor",
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "homepage": "https://typedoc.org",
   "exports": {
     ".": "./dist/index.js",
@@ -27,7 +27,7 @@
     "lunr": "^2.3.9",
     "markdown-it": "^14.1.0",
     "minimatch": "^9.0.4",
-    "shiki": "^1.6.5",
+    "shiki": "^1.9.0",
     "yaml": "^2.4.5"
   },
   "peerDependencies": {
@@ -44,10 +44,10 @@
     "eslint": "^9.5.0",
     "mocha": "^10.4.0",
     "prettier": "3.3.2",
-    "puppeteer": "^22.11.0",
+    "puppeteer": "^22.12.0",
     "ts-node": "^10.9.2",
-    "typescript": "5.5.0-beta",
-    "typescript-eslint": "^7.13.0"
+    "typescript": "5.5.2",
+    "typescript-eslint": "^7.13.1"
   },
   "files": [
     "/bin",

package/tsdoc.json

@@ -3,10 +3,18 @@
     // If updating this, also update tsdoc-defaults.ts
     "noStandardTags": false,
     "tagDefinitions": [
+        {
+            "tagName": "@author",
+            "syntaxKind": "block"
+        },
         {
             "tagName": "@module",
             "syntaxKind": "block"
         },
+        {
+            "tagName": "@type",
+            "syntaxKind": "block"
+        },
         {
             "tagName": "@typedef",
             "syntaxKind": "block"
@@ -92,7 +100,7 @@
         },
         {
             "tagName": "@linkplain",
-            "syntaxKind": "block",
+            "syntaxKind": "inline",
             "allowMultiple": true
         },
         {