typedoc 0.28.6 → 0.28.7

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

@@ -78,6 +78,7 @@ const wantedKinds = {
     [ReflectionKind.Interface]: [
         ts.SyntaxKind.InterfaceDeclaration,
         ts.SyntaxKind.TypeAliasDeclaration,
+        ts.SyntaxKind.ClassDeclaration, // type only exports
     ],
     [ReflectionKind.Constructor]: [ts.SyntaxKind.Constructor],
     [ReflectionKind.Property]: variablePropertyKinds,
@@ -102,7 +103,12 @@ const wantedKinds = {
     [ReflectionKind.Accessor]: [ts.SyntaxKind.PropertyDeclaration],
     [ReflectionKind.GetSignature]: [ts.SyntaxKind.GetAccessor],
     [ReflectionKind.SetSignature]: [ts.SyntaxKind.SetAccessor],
-    [ReflectionKind.TypeAlias]: [ts.SyntaxKind.TypeAliasDeclaration],
+    [ReflectionKind.TypeAlias]: [
+        ts.SyntaxKind.TypeAliasDeclaration,
+        ts.SyntaxKind.FunctionDeclaration, // type only exports
+        // Intentionally not included to avoid comments being copied for variable/alias combos
+        // ts.SyntaxKind.VariableDeclaration,
+    ],
     [ReflectionKind.Reference]: [
         ts.SyntaxKind.NamespaceExport,
         ts.SyntaxKind.ExportSpecifier,

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

@@ -1,4 +1,4 @@
-import { type Comment, type CommentDisplayPart, Reflection, ReflectionSymbolId } from "../../models/index.js";
+import { type CommentDisplayPart, Reflection, ReflectionSymbolId } from "../../models/index.js";
 import { type DeclarationReference } from "#utils";
 export type ExternalResolveResult = {
     target: string;
@@ -16,5 +16,5 @@ export type ExternalSymbolResolver = (ref: DeclarationReference, refl: Reflectio
 export type LinkResolverOptions = {
     preserveLinkText: boolean;
 };
-export declare function resolveLinks(comment: Comment, reflection: Reflection, externalResolver: ExternalSymbolResolver, options: LinkResolverOptions): void;
+export declare function resolveLinks(reflection: Reflection, externalResolver: ExternalSymbolResolver, options: LinkResolverOptions): void;
 export declare function resolvePartLinks(reflection: Reflection, parts: readonly CommentDisplayPart[], externalResolver: ExternalSymbolResolver, options: LinkResolverOptions): CommentDisplayPart[];

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

@@ -1,19 +1,62 @@
 import ts from "typescript";
-import { DeclarationReflection, Reflection, ReflectionKind, ReflectionSymbolId, } from "../../models/index.js";
+import { makeRecursiveVisitor, Reflection, ReflectionKind, ReflectionSymbolId, } from "../../models/index.js";
 import { resolveDeclarationReference } from "./declarationReferenceResolver.js";
 import { maxElementByScore, parseDeclarationReference } from "#utils";
 const urlPrefix = /^(http|ftp)s?:\/\//;
-export function resolveLinks(comment, reflection, externalResolver, options) {
-    comment.summary = resolvePartLinks(reflection, comment.summary, externalResolver, options);
-    for (const tag of comment.blockTags) {
-        tag.content = resolvePartLinks(reflection, tag.content, externalResolver, options);
+export function resolveLinks(reflection, externalResolver, options) {
+    if (reflection.comment) {
+        reflection.comment.summary = resolvePartLinks(reflection, reflection.comment.summary, externalResolver, options);
+        for (const tag of reflection.comment.blockTags) {
+            tag.content = resolvePartLinks(reflection, tag.content, externalResolver, options);
+        }
     }
-    if (reflection instanceof DeclarationReflection && reflection.readme) {
+    if ((reflection.isDeclaration() || reflection.isProject()) && reflection.readme) {
         reflection.readme = resolvePartLinks(reflection, reflection.readme, externalResolver, options);
     }
+    if (reflection.isDeclaration()) {
+        reflection.type?.visit(makeRecursiveVisitor({
+            union: (type) => {
+                type.elementSummaries = type.elementSummaries?.map((parts) => resolvePartLinks(reflection, parts, externalResolver, options));
+            },
+        }));
+    }
     if (reflection.isDocument()) {
         reflection.content = resolvePartLinks(reflection, reflection.content, externalResolver, options);
     }
+    if (reflection.isParameter() &&
+        reflection.type?.type === "reference" &&
+        reflection.type.highlightedProperties) {
+        const resolved = new Map(Array.from(reflection.type.highlightedProperties, ([name, parts]) => {
+            return [
+                name,
+                resolvePartLinks(reflection, parts, externalResolver, options),
+            ];
+        }));
+        reflection.type.highlightedProperties = resolved;
+    }
+    if (reflection.isContainer()) {
+        if (reflection.groups) {
+            for (const group of reflection.groups) {
+                if (group.description) {
+                    group.description = resolvePartLinks(reflection, group.description, externalResolver, options);
+                }
+                if (group.categories) {
+                    for (const cat of group.categories) {
+                        if (cat.description) {
+                            cat.description = resolvePartLinks(reflection, cat.description, externalResolver, options);
+                        }
+                    }
+                }
+            }
+        }
+        if (reflection.categories) {
+            for (const cat of reflection.categories) {
+                if (cat.description) {
+                    cat.description = resolvePartLinks(reflection, cat.description, externalResolver, options);
+                }
+            }
+        }
+    }
 }
 export function resolvePartLinks(reflection, parts, externalResolver, options) {
     return parts.flatMap((part) => processPart(reflection, part, externalResolver, options));
@@ -48,10 +91,10 @@ function resolveLinkTag(reflection, part, externalResolver, options) {
         const tsTargets = reflection.project.getReflectionsFromSymbolId(part.target);
         if (tsTargets.length) {
             // Find the target most likely to have a real url in the generated documentation
-            // 1. A direct export (class, interface, variable)
-            // 2. A property of a direct export (class/interface property)
-            // 3. A property of a type of an export (property on type alias)
-            // 4. Whatever the first symbol found was
+            // 4. A direct export (class, interface, variable)
+            // 3. A property of a direct export (class/interface property)
+            // 2. A property of a type of an export (property on type alias)
+            // 1. Whatever the first symbol found was
             target = maxElementByScore(tsTargets, (r) => {
                 if (r.kindOf(ReflectionKind.SomeExport)) {
                     return 4;

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

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import type { Application } from "../application.js";
-import { Comment, type CommentDisplayPart, type ContainerReflection, type DeclarationReflection, DocumentReflection, type ParameterReflection, ProjectReflection, type Reflection, type ReflectionSymbolId, type SignatureReflection, type SomeType, type TypeParameterReflection } from "../models/index.js";
+import { Comment, type CommentDisplayPart, type ContainerReflection, type DeclarationReflection, DocumentReflection, type ParameterReflection, ProjectReflection, Reflection, type ReflectionSymbolId, type SignatureReflection, type SomeType, type TypeParameterReflection } from "../models/index.js";
 import { Context } from "./context.js";
 import { AbstractComponent } from "../utils/component.js";
 import { type GlobString, MinimalSourceFile } from "#utils";
@@ -187,6 +187,8 @@ export declare class Converter extends AbstractComponent<Application, ConverterE
     addUnknownSymbolResolver(resolver: ExternalSymbolResolver): void;
     /** @internal */
     resolveExternalLink(ref: DeclarationReference, refl: Reflection, part: CommentDisplayPart | undefined, symbolId: ReflectionSymbolId | undefined): ExternalResolveResult | string | undefined;
+    resolveLinks(reflection: Reflection): void;
+    /** @deprecated just pass the reflection */
     resolveLinks(comment: Comment, owner: Reflection): void;
     resolveLinks(parts: readonly CommentDisplayPart[], owner: Reflection): CommentDisplayPart[];
     /**

package/dist/lib/converter/converter.js

@@ -34,7 +34,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import ts from "typescript";
 import { ok } from "assert";
-import { Comment, DocumentReflection, ProjectReflection, ReflectionKind, } from "../models/index.js";
+import { Comment, DocumentReflection, ProjectReflection, Reflection, ReflectionKind, } from "../models/index.js";
 import { Context } from "./context.js";
 import { AbstractComponent } from "../utils/component.js";
 import { getDocumentEntryPoints, Option, readFile } from "../utils/index.js";
@@ -374,8 +374,11 @@ let Converter = (() => {
             }
         }
         resolveLinks(comment, owner) {
-            if (comment instanceof Comment) {
-                resolveLinks(comment, owner, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
+            if (comment instanceof Reflection) {
+                resolveLinks(comment, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
+            }
+            else if (comment instanceof Comment) {
+                resolveLinks(owner, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
             }
             else {
                 return resolvePartLinks(owner, comment, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });

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

@@ -1,4 +1,4 @@
-import { type DeclarationReflection, type DocumentReflection } from "../../models/index.js";
+import { ContainerReflection, type DeclarationReflection, type DocumentReflection } from "../../models/index.js";
 import { ConverterComponent } from "../components.js";
 import type { Converter } from "../converter.js";
 /**
@@ -7,7 +7,7 @@ import type { Converter } from "../converter.js";
  * The handler sets the ´category´ property of all reflections.
  */
 export declare class CategoryPlugin extends ConverterComponent {
-    sortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
+    defaultSortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     accessor defaultCategory: string;
     accessor categoryOrder: string[];
     accessor categorizeByGroup: boolean;
@@ -35,6 +35,7 @@ export declare class CategoryPlugin extends ConverterComponent {
      * @returns An array containing all children of the given reflection categorized
      */
     private getReflectionCategories;
+    getSortFunction(reflection: ContainerReflection): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
     /**
      * Callback used to sort categories by name.
      *

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

@@ -39,6 +39,7 @@ import { getSortFunction, Option } from "../../utils/index.js";
 import { ConverterComponent } from "../components.js";
 import { ConverterEvents } from "../converter-events.js";
 import { i18n } from "#utils";
+import { isValidSortStrategy } from "../../utils/sort.js";
 /**
  * A handler that sorts and categorizes the found reflections in the resolving phase.
  *
@@ -66,7 +67,7 @@ let CategoryPlugin = (() => {
             __esDecorate(this, null, _categorizeByGroup_decorators, { kind: "accessor", name: "categorizeByGroup", static: false, private: false, access: { has: obj => "categorizeByGroup" in obj, get: obj => obj.categorizeByGroup, set: (obj, value) => { obj.categorizeByGroup = value; } }, metadata: _metadata }, _categorizeByGroup_initializers, _categorizeByGroup_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        sortFunction;
+        defaultSortFunction;
         #defaultCategory_accessor_storage = __runInitializers(this, _defaultCategory_initializers, void 0);
         get defaultCategory() { return this.#defaultCategory_accessor_storage; }
         set defaultCategory(value) { this.#defaultCategory_accessor_storage = value; }
@@ -97,7 +98,7 @@ let CategoryPlugin = (() => {
          * Triggered when the converter begins converting a project.
          */
         setup() {
-            this.sortFunction = getSortFunction(this.application.options);
+            this.defaultSortFunction = getSortFunction(this.application.options);
             // Set up static properties
             if (this.defaultCategory) {
                 CategoryPlugin.defaultCategory = this.defaultCategory;
@@ -201,10 +202,21 @@ let CategoryPlugin = (() => {
                 }
             }
             for (const cat of categories.values()) {
-                this.sortFunction(cat.children);
+                this.getSortFunction(parent)(cat.children);
             }
             return Array.from(categories.values());
         }
+        getSortFunction(reflection) {
+            const tag = reflection.comment?.getTag("@sortStrategy");
+            if (tag) {
+                const text = Comment.combineDisplayParts(tag.content);
+                // We don't need to warn about invalid strategies here because the group plugin
+                // runs first and will have already warned.
+                const strategies = text.split(/[,\s]+/).filter(isValidSortStrategy);
+                return getSortFunction(this.application.options, strategies);
+            }
+            return this.defaultSortFunction;
+        }
         /**
          * Callback used to sort categories by name.
          *

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

@@ -8,7 +8,7 @@ import type { Converter } from "../converter.js";
  * The handler sets the `groups` property of all container reflections.
  */
 export declare class GroupPlugin extends ConverterComponent {
-    sortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
+    defaultSortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     accessor groupOrder: string[];
     accessor sortEntryPoints: boolean;
     accessor groupReferencesByType: boolean;
@@ -40,6 +40,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
     getReflectionGroups(parent: ContainerReflection, reflections: Array<DeclarationReflection | DocumentReflection>): ReflectionGroup[];
+    getSortFunction(reflection: ContainerReflection): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
     /**
      * Callback used to sort groups by name.
      */

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

@@ -35,13 +35,13 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 import { ContainerReflection, ReferenceReflection, ReflectionKind, } from "../../models/index.js";
 import { ReflectionGroup } from "../../models/ReflectionGroup.js";
 import { ConverterComponent } from "../components.js";
-import { getSortFunction } from "../../utils/sort.js";
+import { getSortFunction, isValidSortStrategy, SORT_STRATEGIES } from "../../utils/sort.js";
 import { Option } from "../../utils/index.js";
 import { Comment } from "../../models/index.js";
 import { ConverterEvents } from "../converter-events.js";
 import { ApplicationEvents } from "../../application-events.js";
 import assert from "assert";
-import { i18n } from "#utils";
+import { i18n, partition } from "#utils";
 // Same as the defaultKindSortOrder in sort.ts
 const defaultGroupOrder = [
     ReflectionKind.Document,
@@ -89,7 +89,7 @@ let GroupPlugin = (() => {
             __esDecorate(this, null, _groupReferencesByType_decorators, { kind: "accessor", name: "groupReferencesByType", static: false, private: false, access: { has: obj => "groupReferencesByType" in obj, get: obj => obj.groupReferencesByType, set: (obj, value) => { obj.groupReferencesByType = value; } }, metadata: _metadata }, _groupReferencesByType_initializers, _groupReferencesByType_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        sortFunction;
+        defaultSortFunction;
         #groupOrder_accessor_storage = __runInitializers(this, _groupOrder_initializers, void 0);
         get groupOrder() { return this.#groupOrder_accessor_storage; }
         set groupOrder(value) { this.#groupOrder_accessor_storage = value; }
@@ -130,25 +130,26 @@ let GroupPlugin = (() => {
             }
         }
         setup() {
-            this.sortFunction = getSortFunction(this.application.options);
+            this.defaultSortFunction = getSortFunction(this.application.options);
             GroupPlugin.WEIGHTS = this.groupOrder;
             if (GroupPlugin.WEIGHTS.length === 0) {
                 GroupPlugin.WEIGHTS = defaultGroupOrder.map((kind) => ReflectionKind.pluralString(kind));
             }
         }
         group(reflection) {
+            const sortFunction = this.getSortFunction(reflection);
             if (reflection.childrenIncludingDocuments && !reflection.groups) {
                 if (reflection.children) {
                     if (this.sortEntryPoints ||
                         !reflection.children.some((c) => c.kindOf(ReflectionKind.Module))) {
-                        this.sortFunction(reflection.children);
-                        this.sortFunction(reflection.documents || []);
-                        this.sortFunction(reflection.childrenIncludingDocuments);
+                        sortFunction(reflection.children);
+                        sortFunction(reflection.documents || []);
+                        sortFunction(reflection.childrenIncludingDocuments);
                     }
                 }
                 else if (reflection.documents) {
-                    this.sortFunction(reflection.documents);
-                    this.sortFunction(reflection.childrenIncludingDocuments);
+                    sortFunction(reflection.documents);
+                    sortFunction(reflection.childrenIncludingDocuments);
                 }
                 if (reflection.comment?.hasModifier("@disableGroups")) {
                     return;
@@ -239,6 +240,19 @@ let GroupPlugin = (() => {
             }
             return Array.from(groups.values()).sort(GroupPlugin.sortGroupCallback);
         }
+        getSortFunction(reflection) {
+            const tag = reflection.comment?.getTag("@sortStrategy");
+            if (tag) {
+                const text = Comment.combineDisplayParts(tag.content);
+                const strategies = text.split(/[,\s]+/);
+                const [valid, invalid] = partition(strategies, isValidSortStrategy);
+                for (const inv of invalid) {
+                    this.application.logger.warn(i18n.comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid(reflection.getFriendlyFullName(), inv, SORT_STRATEGIES.join("\n\t")));
+                }
+                return getSortFunction(this.application.options, valid);
+            }
+            return this.defaultSortFunction;
+        }
         /**
          * Callback used to sort groups by name.
          */

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

@@ -1,7 +1,7 @@
 import { ConverterComponent } from "../components.js";
 import type { Context, Converter } from "../../converter/index.js";
 import { type ValidationOptions } from "../../utils/index.js";
-import { type ProjectReflection } from "../../models/index.js";
+import type { ProjectReflection } from "../../models/index.js";
 /**
  * A plugin that resolves `{@link Foo}` tags.
  */
@@ -10,5 +10,4 @@ export declare class LinkResolverPlugin extends ConverterComponent {
     constructor(owner: Converter);
     onResolve(context: Context): void;
     resolveLinks(project: ProjectReflection): void;
-    private resolveCategoryLinks;
 }

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

@@ -35,7 +35,6 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 import { ConverterComponent } from "../components.js";
 import { ConverterEvents } from "../converter-events.js";
 import { Option } from "../../utils/index.js";
-import { ContainerReflection, makeRecursiveVisitor, } from "../../models/index.js";
 import { discoverAllReferenceTypes } from "../../utils/reflections.js";
 import { ApplicationEvents } from "../../application-events.js";
 /**
@@ -68,55 +67,7 @@ let LinkResolverPlugin = (() => {
         resolveLinks(project) {
             for (const id in project.reflections) {
                 const reflection = project.reflections[id];
-                if (reflection.comment) {
-                    this.owner.resolveLinks(reflection.comment, reflection);
-                }
-                if (reflection.isDeclaration()) {
-                    reflection.type?.visit(makeRecursiveVisitor({
-                        union: (type) => {
-                            type.elementSummaries = type.elementSummaries?.map((parts) => this.owner.resolveLinks(parts, reflection));
-                        },
-                    }));
-                    if (reflection.readme) {
-                        reflection.readme = this.owner.resolveLinks(reflection.readme, reflection);
-                    }
-                }
-                if (reflection.isDocument()) {
-                    reflection.content = this.owner.resolveLinks(reflection.content, reflection);
-                }
-                if (reflection.isParameter() &&
-                    reflection.type?.type === "reference" &&
-                    reflection.type.highlightedProperties) {
-                    const resolved = new Map(Array.from(reflection.type.highlightedProperties, ([name, parts]) => {
-                        return [
-                            name,
-                            this.owner.resolveLinks(parts, reflection),
-                        ];
-                    }));
-                    reflection.type.highlightedProperties = resolved;
-                }
-                if (reflection instanceof ContainerReflection) {
-                    if (reflection.groups) {
-                        for (const group of reflection.groups) {
-                            if (group.description) {
-                                group.description = this.owner.resolveLinks(group.description, reflection);
-                            }
-                            if (group.categories) {
-                                for (const cat of group.categories) {
-                                    this.resolveCategoryLinks(cat, reflection);
-                                }
-                            }
-                        }
-                    }
-                    if (reflection.categories) {
-                        for (const cat of reflection.categories) {
-                            this.resolveCategoryLinks(cat, reflection);
-                        }
-                    }
-                }
-            }
-            if (project.readme) {
-                project.readme = this.owner.resolveLinks(project.readme, project);
+                this.owner.resolveLinks(reflection);
             }
             for (const { type, owner } of discoverAllReferenceTypes(project, false)) {
                 if (!type.reflection) {
@@ -132,11 +83,6 @@ let LinkResolverPlugin = (() => {
                 }
             }
         }
-        resolveCategoryLinks(category, owner) {
-            if (category.description) {
-                category.description = this.owner.resolveLinks(category.description, owner);
-            }
-        }
     };
 })();
 export { LinkResolverPlugin };

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

@@ -140,7 +140,7 @@ let GitRepository = (() => {
          */
         static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
             gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
-            if (!gitRevision)
+            if (gitRevision == "HEAD")
                 return; // Will only happen in a repo with no commits.
             let urlTemplate;
             if (sourceLinkTemplate) {

package/dist/lib/internationalization/internationalization.js

@@ -16,7 +16,7 @@ export function loadTranslations(lang) {
         return req(`./locales/${lang}.cjs`);
     }
     catch {
-        return {};
+        return loadTranslations("en");
     }
 }
 /**

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

@@ -72,6 +72,7 @@ module.exports = {
     not_all_search_group_boosts_used_0: `Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}`,
     comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: `Comment for {0} includes @categoryDescription for "{1}", but no child is placed in that category`,
     comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: `Comment for {0} includes @groupDescription for "{1}", but no child is placed in that group`,
+    comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: `Comment for {0} specifies @sortStrategy with "{1}", which is an invalid sort strategy, the following are valid:\n\t{2}`,
     label_0_for_1_cannot_be_referenced: `The label "{0}" for {1} cannot be referenced with a declaration reference. Labels may only contain A-Z, 0-9, and _, and may not start with a number`,
     modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: `The modifier tag {0} is mutually exclusive with {1} in the comment for {2}`,
     signature_0_has_unused_param_with_name_1: `The signature {0} has an @param with name "{1}", which was not used`,
@@ -274,13 +275,14 @@ module.exports = {
     useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set",
     favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object",
+    option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings",
     option_0_must_be_a_function: "The '{0}' option must be a function",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values`,
     visibility_filters_only_include_0: `visibilityFilters can only include the following non-@ keys: {0}`,
     visibility_filters_must_be_booleans: `All values of visibilityFilters must be booleans`,
     option_0_values_must_be_numbers: "All values of {0} must be numbers",
     option_0_values_must_be_array_of_tags: "{0} must be an array of valid tag names",
-    option_0_specified_1_but_only_2_is_valid: `{0} may only specify known values, and invalid values were provided ({1}). The valid sort strategies are:\n{2}`,
+    option_0_specified_1_but_only_2_is_valid: `{0} may only specify known values, and invalid values were provided ({1}). The valid options are:\n{2}`,
     option_outputs_must_be_array: `"outputs" option must be an array of { name: string, path: string, options?: TypeDocOptions } values.`,
     specified_output_0_has_not_been_defined: `Specified output "{0}" has not been defined.`,
     // https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

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

@@ -66,6 +66,7 @@ declare const _default: {
     readonly not_all_search_group_boosts_used_0: "Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}";
     readonly comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "Comment for {0} includes @categoryDescription for \"{1}\", but no child is placed in that category";
     readonly comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "Comment for {0} includes @groupDescription for \"{1}\", but no child is placed in that group";
+    readonly comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: "Comment for {0} specifies @sortStrategy with \"{1}\", which is an invalid sort strategy, the following are valid:\n\t{2}";
     readonly label_0_for_1_cannot_be_referenced: "The label \"{0}\" for {1} cannot be referenced with a declaration reference. Labels may only contain A-Z, 0-9, and _, and may not start with a number";
     readonly modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: "The modifier tag {0} is mutually exclusive with {1} in the comment for {2}";
     readonly signature_0_has_unused_param_with_name_1: "The signature {0} has an @param with name \"{1}\", which was not used";
@@ -258,13 +259,14 @@ declare const _default: {
     readonly useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set";
     readonly favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}";
     readonly option_0_must_be_an_object: "The '{0}' option must be a non-array object";
+    readonly option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings";
     readonly option_0_must_be_a_function: "The '{0}' option must be a function";
     readonly option_0_must_be_object_with_urls: "{0} must be an object with string labels as keys and URL values";
     readonly visibility_filters_only_include_0: "visibilityFilters can only include the following non-@ keys: {0}";
     readonly visibility_filters_must_be_booleans: "All values of visibilityFilters must be booleans";
     readonly option_0_values_must_be_numbers: "All values of {0} must be numbers";
     readonly option_0_values_must_be_array_of_tags: "{0} must be an array of valid tag names";
-    readonly option_0_specified_1_but_only_2_is_valid: "{0} may only specify known values, and invalid values were provided ({1}). The valid sort strategies are:\n{2}";
+    readonly option_0_specified_1_but_only_2_is_valid: "{0} may only specify known values, and invalid values were provided ({1}). The valid options are:\n{2}";
     readonly option_outputs_must_be_array: "\"outputs\" option must be an array of { name: string, path: string, options?: TypeDocOptions } values.";
     readonly specified_output_0_has_not_been_defined: "Specified output \"{0}\" has not been defined.";
     readonly alert_note: "Note";

package/dist/lib/models/Comment.js

@@ -74,7 +74,7 @@ export class CommentTag {
      */
     similarTo(other) {
         return (this.tag === other.tag &&
-            this.name === other.tag &&
+            this.name === other.name &&
             Comment.combineDisplayParts(this.content) ===
                 Comment.combineDisplayParts(other.content));
     }

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

@@ -49,6 +49,7 @@ export declare abstract class ContainerReflection extends Reflection {
     getChildrenByKind(kind: ReflectionKind): DeclarationReflection[];
     addChild(child: Reflection): void;
     removeChild(child: DeclarationReflection | DocumentReflection): void;
+    isContainer(): this is ContainerReflection;
     traverse(callback: TraverseCallback): void;
     toObject(serializer: Serializer): JSONOutput.ContainerReflection;
     fromObject(de: Deserializer, obj: JSONOutput.ContainerReflection): void;

package/dist/lib/models/ContainerReflection.js

@@ -100,6 +100,9 @@ export class ContainerReflection extends Reflection {
             delete this.childrenIncludingDocuments;
         }
     }
+    isContainer() {
+        return true;
+    }
     traverse(callback) {
         for (const child of this.children?.slice() || []) {
             if (callback(child, TraverseProperty.Children) === false) {

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

@@ -10,6 +10,7 @@ import type { ParameterReflection } from "./ParameterReflection.js";
 import type { ReferenceReflection } from "./ReferenceReflection.js";
 import type { SignatureReflection } from "./SignatureReflection.js";
 import type { TypeParameterReflection } from "./TypeParameterReflection.js";
+import type { ContainerReflection } from "./ContainerReflection.js";
 /**
  * Reset the reflection id.
  *
@@ -193,6 +194,7 @@ export declare abstract class Reflection {
     isParameter(): this is ParameterReflection;
     isDocument(): this is DocumentReflection;
     isReference(): this is ReferenceReflection;
+    isContainer(): this is ContainerReflection;
     /**
      * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
      */

package/dist/lib/models/Reflection.js

@@ -419,6 +419,9 @@ let Reflection = (() => {
         isReference() {
             return this.variant === "reference";
         }
+        isContainer() {
+            return false;
+        }
         /**
          * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
          */

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

@@ -8,7 +8,7 @@ export function moduleReflection(context, mod) {
         mod.hasComment() && (JSX.createElement("section", { class: "tsd-panel tsd-comment" },
             context.commentSummary(mod),
             context.commentTags(mod))),
-        mod.isDeclaration() && mod.kind === ReflectionKind.Module && mod.readme?.length && (JSX.createElement("section", { class: "tsd-panel tsd-typography" },
+        mod.isDeclaration() && mod.kind === ReflectionKind.Module && !!mod.readme?.length && (JSX.createElement("section", { class: "tsd-panel tsd-typography" },
             JSX.createElement(JSX.Raw, { html: context.markdown(mod.readme) }))),
         sections.map((section) => {
             if (!isNoneSection(section)) {

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

@@ -53,7 +53,7 @@ export function settings(context) {
                 context.icons.chevronDown(),
                 JSX.createElement("h3", null, i18n.theme_settings())),
             JSX.createElement("div", { class: "tsd-accordion-details" },
-                visibilityOptions.length && (JSX.createElement("div", { class: "tsd-filter-visibility" },
+                !!visibilityOptions.length && (JSX.createElement("div", { class: "tsd-filter-visibility" },
                     JSX.createElement("span", { class: "settings-label" }, i18n.theme_member_visibility()),
                     JSX.createElement("ul", { id: "tsd-filter-options" }, ...visibilityOptions))),
                 JSX.createElement("div", { class: "tsd-theme-toggle" },

package/dist/lib/output/themes/default/templates/hierarchy.js

@@ -21,7 +21,7 @@ function fullHierarchy(context, root, seen) {
         JSX.createElement("a", { href: context.urlTo(root) },
             context.reflectionIcon(root),
             root.name),
-        children.length && JSX.createElement("ul", null, children)));
+        !!children.length && JSX.createElement("ul", null, children)));
 }
 export function hierarchyTemplate(context, props) {
     const seen = new Set();

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

@@ -127,6 +127,15 @@ export var ParameterType;
      */
     ParameterType[ParameterType["Flags"] = 12] = "Flags";
 })(ParameterType || (ParameterType = {}));
+function toStringArray(value, option) {
+    if (Array.isArray(value) && value.every(v => typeof v === "string")) {
+        return value;
+    }
+    else if (typeof value === "string") {
+        return [value];
+    }
+    throw new Error(i18n.option_0_must_be_an_array_of_string(option.name));
+}
 const converters = {
     [ParameterType.String](value, option) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -164,36 +173,18 @@ const converters = {
         return !!value;
     },
     [ParameterType.Array](value, option) {
-        let strArrValue = [];
-        if (Array.isArray(value)) {
-            strArrValue = value.map(String);
-        }
-        else if (typeof value === "string") {
-            strArrValue = [value];
-        }
+        const strArrValue = toStringArray(value, option);
         option.validate?.(strArrValue);
         return strArrValue;
     },
     [ParameterType.PathArray](value, option, configPath) {
-        let strArrValue = [];
-        if (Array.isArray(value)) {
-            strArrValue = value.map(String);
-        }
-        else if (typeof value === "string") {
-            strArrValue = [value];
-        }
+        const strArrValue = toStringArray(value, option);
         const normalized = strArrValue.map((path) => normalizePath(resolve(configPath, path)));
         option.validate?.(normalized);
         return normalized;
     },
     [ParameterType.ModuleArray](value, option, configPath) {
-        let strArrValue = [];
-        if (Array.isArray(value)) {
-            strArrValue = value.map(String);
-        }
-        else if (typeof value === "string") {
-            strArrValue = [value];
-        }
+        const strArrValue = toStringArray(value, option);
         const resolved = resolveModulePaths(strArrValue, configPath);
         option.validate?.(resolved);
         return resolved;
@@ -210,7 +201,8 @@ const converters = {
             }
             return createGlobString(configPath, s);
         };
-        const globs = Array.isArray(value) ? value.map(toGlobString) : [toGlobString(value)];
+        const strArrValue = toStringArray(value, option);
+        const globs = strArrValue.map(toGlobString);
         option.validate?.(globs);
         return globs;
     },

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

@@ -740,10 +740,7 @@ export function addTypeDocOptions(options) {
         type: ParameterType.Array,
         defaultValue: OptionDefaults.sort,
         validate(value) {
-            const invalid = new Set(value);
-            for (const v of SORT_STRATEGIES) {
-                invalid.delete(v);
-            }
+            const invalid = setDifference(value, SORT_STRATEGIES);
             if (invalid.size !== 0) {
                 throw new Error(i18n.option_0_specified_1_but_only_2_is_valid("sort", Array.from(invalid).join(", "), SORT_STRATEGIES.join(", ")));
             }

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

@@ -35,6 +35,7 @@ export const blockTags = [
     "@return",
     "@satisfies",
     "@since",
+    "@sortStrategy",
     "@template", // Alias for @typeParam
     "@type",
     "@typedef",

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

@@ -7,4 +7,5 @@ import type { Options } from "./options/index.js";
 import type { DocumentReflection } from "../models/index.js";
 export declare const SORT_STRATEGIES: readonly ["source-order", "alphabetical", "alphabetical-ignoring-documents", "enum-value-ascending", "enum-value-descending", "enum-member-source-order", "static-first", "instance-first", "visibility", "required-first", "kind", "external-last", "documents-first", "documents-last"];
 export type SortStrategy = (typeof SORT_STRATEGIES)[number];
-export declare function getSortFunction(opts: Options): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
+export declare function isValidSortStrategy(strategy: string): strategy is SortStrategy;
+export declare function getSortFunction(opts: Options, strategies?: readonly SortStrategy[]): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;

package/dist/lib/utils/sort.js

@@ -124,7 +124,10 @@ const sorts = {
             b.kindOf(ReflectionKind.Document));
     },
 };
-export function getSortFunction(opts) {
+export function isValidSortStrategy(strategy) {
+    return SORT_STRATEGIES.includes(strategy);
+}
+export function getSortFunction(opts, strategies = opts.getValue("sort")) {
     const kindSortOrder = opts
         .getValue("kindSortOrder")
         .map((k) => ReflectionKind[k]);
@@ -133,7 +136,6 @@ export function getSortFunction(opts) {
             kindSortOrder.push(ReflectionKind[kind]);
         }
     }
-    const strategies = opts.getValue("sort");
     const data = { kindSortOrder };
     return function sortReflections(reflections) {
         reflections.sort((a, b) => {

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

@@ -50,9 +50,8 @@ 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> | undefined, 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 firstDefined<T, U>(array: readonly T[], 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[];
 export declare function aggregate<T>(arr: T[], fn: (item: T) => number): number;
-export declare function aggregateWithJoiner<T>(arr: T[], fn: (item: T) => number, joiner: string): number;
 export declare function joinArray<T>(arr: readonly T[] | undefined, joiner: string, mapper: (item: T) => string): string;
 export declare function maxElementByScore<T>(arr: readonly T[], score: (a: T) => number): T | undefined;

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

@@ -115,9 +115,6 @@ export function filterMap(iter, fn) {
     return result;
 }
 export 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) {
@@ -132,10 +129,6 @@ export function filter(array, predicate) {
 export function aggregate(arr, fn) {
     return arr.reduce((sum, it) => sum + fn(it), 0);
 }
-export function aggregateWithJoiner(arr, fn, joiner) {
-    return (arr.reduce((sum, it) => sum + fn(it), 0) +
-        (arr.length - 1) * joiner.length);
-}
 export function joinArray(arr, joiner, mapper) {
     if (arr?.length) {
         return arr.map(mapper).join(joiner);

package/dist/lib/utils-common/jsx.elements.d.ts

@@ -131,7 +131,7 @@ export interface JsxElement {
     props: object | null;
     children: JsxChildren[];
 }
-export type JsxChildren = JsxElement | string | number | null | undefined | JsxChildren[];
+export type JsxChildren = JsxElement | string | number | boolean | bigint | null | undefined | JsxChildren[];
 /**
  * The common properties that may appear on any HTML element.
  *

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

@@ -71,7 +71,7 @@ export function setRenderSettings(options) {
     renderPretty = options.pretty;
 }
 export function renderElement(element) {
-    if (!element || typeof element === "boolean") {
+    if (!element) {
         return "";
     }
     const { tag, props, children } = element;
@@ -128,12 +128,12 @@ export function renderElement(element) {
     return html;
     function renderChildren(children) {
         for (const child of children) {
-            if (!child)
+            if (typeof child === "boolean")
                 continue;
             if (Array.isArray(child)) {
                 renderChildren(child);
             }
-            else if (typeof child === "string" || typeof child === "number") {
+            else if (typeof child === "string" || typeof child === "number" || typeof child === "bigint") {
                 html += escapeHtml(child.toString());
             }
             else {
@@ -148,7 +148,7 @@ export function renderElement(element) {
  * @internal
  */
 export function renderElementToText(element) {
-    if (!element || typeof element === "boolean") {
+    if (!element) {
         return "";
     }
     const { tag, props, children } = element;
@@ -170,12 +170,13 @@ export function renderElementToText(element) {
     return html;
     function renderChildren(children) {
         for (const child of children) {
-            if (!child)
+            if (typeof child === "boolean")
                 continue;
             if (Array.isArray(child)) {
                 renderChildren(child);
             }
-            else if (typeof child === "string" || typeof child === "number") {
+            else if (typeof child === "string" || typeof child === "number" || typeof child === "bigint") {
+                // Turn non-breaking spaces into regular spaces
                 html += child.toString().replaceAll("\u00A0", " ");
             }
             else {

package/dist/lib/utils-common/map.d.ts

@@ -15,7 +15,7 @@ export declare class StableKeyMap<K extends {
     has(key: K): boolean;
     clear(): void;
     delete(key: K): boolean;
-    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    forEach(callbackfn: (value: V, key: K, map: StableKeyMap<K, V>) => void, thisArg?: any): void;
     entries(): IterableIterator<[K, V]>;
     keys(): IterableIterator<K>;
     values(): IterableIterator<V>;

package/dist/lib/validation/links.js

@@ -25,9 +25,6 @@ export function validateLinks(project, logger) {
     for (const id in project.reflections) {
         checkReflection(project.reflections[id], logger);
     }
-    if (!(project.id in project.reflections)) {
-        checkReflection(project, logger);
-    }
 }
 function checkReflection(reflection, logger) {
     if (reflection.isProject() || reflection.isDeclaration()) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.28.6",
+  "version": "0.28.7",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {
@@ -31,32 +31,32 @@
     "pnpm": ">= 10"
   },
   "dependencies": {
-    "@gerrit0/mini-shiki": "^3.2.2",
+    "@gerrit0/mini-shiki": "^3.7.0",
     "lunr": "^2.3.9",
     "markdown-it": "^14.1.0",
     "minimatch": "^9.0.5",
-    "yaml": "^2.7.1"
+    "yaml": "^2.8.0"
   },
   "peerDependencies": {
     "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x"
   },
   "devDependencies": {
-    "@eslint/js": "^9.24.0",
+    "@eslint/js": "^9.30.0",
     "@types/lunr": "^2.3.7",
     "@types/markdown-it": "^14.1.2",
     "@types/mocha": "^10.0.10",
     "@types/node": "18",
     "@typestrong/fs-fixture-builder": "github:TypeStrong/fs-fixture-builder#34113409e3a171e68ce5e2b55461ef5c35591cfe",
     "c8": "^10.1.3",
-    "dprint": "^0.49.1",
-    "esbuild": "^0.25.2",
-    "eslint": "^9.24.0",
-    "mocha": "^11.1.0",
-    "puppeteer": "^24.6.0",
-    "semver": "^7.7.1",
-    "tsx": "^4.19.3",
+    "dprint": "^0.50.0",
+    "esbuild": "^0.25.5",
+    "eslint": "^9.30.0",
+    "mocha": "^11.7.1",
+    "puppeteer": "^24.11.1",
+    "semver": "^7.7.2",
+    "tsx": "^4.20.3",
     "typescript": "5.8.3",
-    "typescript-eslint": "^8.29.0"
+    "typescript-eslint": "^8.35.0"
   },
   "files": [
     "/bin",

package/static/style.css

@@ -504,15 +504,8 @@
     body {
         background: var(--color-background);
         font-family:
-            -apple-system,
-            BlinkMacSystemFont,
-            "Segoe UI",
-            "Noto Sans",
-            Helvetica,
-            Arial,
-            sans-serif,
-            "Apple Color Emoji",
-            "Segoe UI Emoji";
+            -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+            Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
         font-size: 16px;
         color: var(--color-text);
         margin: 0;

package/tsdoc.json

@@ -237,6 +237,10 @@
         {
             "tagName": "@useDeclaredType",
             "syntaxKind": "modifier"
+        },
+        {
+            "tagName": "@sortStrategy",
+            "syntaxKind": "block"
         }
     ]
 }