typedoc 0.28.5 → 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/comments/textParser.d.ts

@@ -18,6 +18,7 @@ import type { NormalizedPath, TranslatedString } from "#utils";
  */
 export declare class TextParserReentryState {
     withinLinkLabel: boolean;
+    withinLinkDest: boolean;
     private lastPartWasNewline;
     checkState(token: Token): void;
 }

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

@@ -10,17 +10,20 @@ const MdHelpers = new MarkdownIt().helpers;
  */
 export class TextParserReentryState {
     withinLinkLabel = false;
+    withinLinkDest = false;
     lastPartWasNewline = false;
     checkState(token) {
         switch (token.kind) {
             case TokenSyntaxKind.Code:
                 if (/\n\s*\n/.test(token.text)) {
                     this.withinLinkLabel = false;
+                    this.withinLinkDest = false;
                 }
                 break;
             case TokenSyntaxKind.NewLine:
                 if (this.lastPartWasNewline) {
                     this.withinLinkLabel = false;
+                    this.withinLinkDest = false;
                 }
                 break;
         }
@@ -33,16 +36,17 @@ export class TextParserReentryState {
  */
 export function textContent(sourcePath, token, i18n, warning, outContent, files, atNewLine, reentry) {
     let lastPartEnd = 0;
+    let canEndMarkdownLink = true;
     const data = {
         sourcePath,
         token,
         pos: 0, // relative to the token
-        i18n,
         warning,
         files: files,
         atNewLine,
     };
     function addRef(ref) {
+        canEndMarkdownLink = true;
         outContent.push({
             kind: "text",
             text: token.text.slice(lastPartEnd, ref.pos),
@@ -66,10 +70,15 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
         }
     }
     while (data.pos < token.text.length) {
-        const link = checkMarkdownLink(data, reentry);
-        if (link) {
-            addRef(link);
-            continue;
+        if (canEndMarkdownLink) {
+            const link = checkMarkdownLink(data, reentry);
+            if (link) {
+                addRef(link);
+                continue;
+            }
+            // If we're within a Markdown link, then `checkMarkdownLink`
+            // already scanned `token` up to a line feed (if any).
+            canEndMarkdownLink = !reentry.withinLinkLabel && !reentry.withinLinkDest;
         }
         const reference = checkReference(data);
         if (reference) {
@@ -81,7 +90,10 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
             addRef(tagLink);
             continue;
         }
-        data.atNewLine = token.text[data.pos] === "\n";
+        const atNewLine = token.text[data.pos] === "\n";
+        data.atNewLine = atNewLine;
+        if (atNewLine && !reentry.withinLinkDest)
+            canEndMarkdownLink = true;
         ++data.pos;
     }
     if (lastPartEnd !== token.text.length) {
@@ -101,9 +113,8 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
 function checkMarkdownLink(data, reentry) {
     const { token, sourcePath, files } = data;
     let searchStart;
-    if (reentry.withinLinkLabel) {
+    if (reentry.withinLinkLabel || reentry.withinLinkDest) {
         searchStart = data.pos;
-        reentry.withinLinkLabel = false;
     }
     else if (token.text[data.pos] === "[") {
         searchStart = data.pos + 1;
@@ -111,34 +122,60 @@ function checkMarkdownLink(data, reentry) {
     else {
         return;
     }
-    const labelEnd = findLabelEnd(token.text, searchStart);
-    if (labelEnd === -1) {
-        // This markdown link might be split across multiple display parts
-        // [ `text` ](link)
-        // ^^ text
-        //   ^^^^^^ code
-        //         ^^^^^^^^ text
-        reentry.withinLinkLabel = true;
-        return;
+    if (!reentry.withinLinkDest) {
+        const labelEnd = findLabelEnd(token.text, searchStart);
+        if (labelEnd === -1 || token.text[labelEnd] === "\n") {
+            // This markdown link might be split across multiple lines or input tokens
+            //     [prefix `code` suffix](target)
+            //     ........^^^^^^................
+            // Unless we encounter two consecutive line feeds, expect it to keep going.
+            reentry.withinLinkLabel = labelEnd !== data.pos || !data.atNewLine;
+            return;
+        }
+        reentry.withinLinkLabel = false;
+        if (!token.text.startsWith("](", labelEnd))
+            return;
+        searchStart = labelEnd + 2;
     }
-    if (token.text[labelEnd] === "]" && token.text[labelEnd + 1] === "(") {
-        const link = MdHelpers.parseLinkDestination(token.text, labelEnd + 2, token.text.length);
-        if (link.ok) {
-            // Only make a relative-link display part if it's actually a relative link.
-            // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
-            if (isRelativePath(link.str)) {
-                const { target, anchor } = files.register(sourcePath, link.str) || { target: undefined, anchor: undefined };
-                return {
-                    pos: labelEnd + 2,
-                    end: link.pos,
-                    target,
-                    targetAnchor: anchor,
-                };
-            }
-            // This was a link, skip ahead to ensure we don't happen to parse
-            // something else as a link within the link.
-            data.pos = link.pos - 1;
+    // Skip whitespace (including line breaks) between "](" and the link destination.
+    // https://spec.commonmark.org/0.31.2/#links
+    const end = token.text.length;
+    let lookahead = searchStart;
+    for (let newlines = 0;; ++lookahead) {
+        if (lookahead === end) {
+            reentry.withinLinkDest = true;
+            return;
+        }
+        switch (token.text[lookahead]) {
+            case "\n":
+                if (++newlines === 2) {
+                    reentry.withinLinkDest = false;
+                    return;
+                }
+                continue;
+            case " ":
+            case "\t":
+                continue;
         }
+        break;
+    }
+    reentry.withinLinkDest = false;
+    const link = MdHelpers.parseLinkDestination(token.text, lookahead, end);
+    if (link.ok) {
+        // Only make a relative-link display part if it's actually a relative link.
+        // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
+        if (isRelativePath(link.str)) {
+            const { target, anchor } = files.register(sourcePath, link.str) || { target: undefined, anchor: undefined };
+            return {
+                pos: lookahead,
+                end: link.pos,
+                target,
+                targetAnchor: anchor,
+            };
+        }
+        // This was a link, skip ahead to ensure we don't happen to parse
+        // something else as a link within the link.
+        data.pos = link.pos - 1;
     }
 }
 /**
@@ -230,6 +267,11 @@ function isRelativePath(link) {
 function findLabelEnd(text, pos) {
     while (pos < text.length) {
         switch (text[pos]) {
+            case "\\":
+                ++pos;
+                if (pos < text.length && text[pos] === "\n")
+                    return pos;
+                break;
             case "\n":
             case "]":
             case "[":

package/dist/lib/converter/context.js

@@ -130,14 +130,25 @@ export class Context {
         return reflection;
     }
     postReflectionCreation(reflection, symbol, exportSymbol) {
-        if (exportSymbol &&
-            reflection.kind &
-                (ReflectionKind.SomeModule | ReflectionKind.Reference)) {
+        // Allow comments on export declarations to take priority over comments directly
+        // on the symbol to enable overriding comments on modules/references, #1504
+        if (!reflection.comment &&
+            exportSymbol &&
+            (reflection.kind &
+                (ReflectionKind.SomeModule | ReflectionKind.Reference))) {
             reflection.comment = this.getComment(exportSymbol, reflection.kind);
         }
+        // If that didn't get us a comment (the normal case), then get the comment from
+        // the source declarations, this is the common case.
         if (symbol && !reflection.comment) {
             reflection.comment = this.getComment(symbol, reflection.kind);
         }
+        // If we still don't have a comment, check for any comments on the export declaration,
+        // we don't have to worry about functions being weird in this case as the regular declaration
+        // doesn't have any comment.
+        if (exportSymbol && !reflection.comment) {
+            reflection.comment = this.getComment(exportSymbol, ReflectionKind.Reference);
+        }
         if (this.shouldBeStatic) {
             reflection.setFlag(ReflectionFlag.Static);
         }

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";
@@ -305,6 +305,9 @@ let Converter = (() => {
             const programs = unique(entryPoints.map((e) => e.program));
             this.externalPatternCache = void 0;
             const project = new ProjectReflection(this.application.options.getValue("name"), this.application.files);
+            if (this.owner.options.packageDir) {
+                project.files.registerReflectionPath(normalizePath(this.owner.options.packageDir), project);
+            }
             const context = new Context(this, programs, project);
             this.trigger(Converter.EVENT_BEGIN, context);
             this.addProjectDocuments(project);
@@ -371,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;
 }