Add support for @sortStrategy

Resolves #2965

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,10 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+- Introduced the `@sortStrategy` tag to override the `sort` option on a specific reflection, #2965.
+
 ### Bug Fixes
 
 - Classes and functions exported with `export { type X }` are no longer missing comments, #2970.

site/options/organization.md

@@ -81,6 +81,9 @@ Specifies the sort order for members. Sorting strategies will be applied in orde
 If an earlier sorting strategy determines the relative ordering of two reflections, later
 ordering strategies will not be applied.
 
+This option defines the default sort strategy, the [`@sortStrategy`](../tags/sortStrategy.md)
+tag may be used to override it for individual reflections.
+
 For example, with the setting `["static-first", "visibility"]`, TypeDoc will first compare two
 reflections by if they are static or not, and if that comparison returns equal, will check the
 visibility of each reflection. On the other hand, if `["visibility", "static-first"]` is specified,
@@ -104,6 +107,18 @@ The available sorting strategies are:
 - `documents-last`
 - `alphabetical-ignoring-documents`
 
+The default sort order is:
+
+```json
+{
+    "sort": [
+        "kind",
+        "instance-first",
+        "alphabetical-ignoring-documents"
+    ]
+}
+```
+
 ## sortEntryPoints
 
 ```bash

site/tags.md

@@ -47,8 +47,9 @@ children:
     - tags/remarks.md
     - tags/returns.md
     - tags/sealed.md
-    - tags/since.md
     - tags/see.md
+    - tags/since.md
+    - tags/sortStrategy.md
     - tags/summary.md
     - tags/template.md
     - tags/throws.md
@@ -130,6 +131,7 @@ examples for how to use the export ([`@example`](./tags/example.md)).
 - [`@returns`, `@return`](./tags/returns.md)
 - [`@see`](./tags/see.md)
 - [`@since`](./tags/since.md)
+- [`@sortStrategy`](./tags/sortStrategy.md)
 - [`@summary`](./tags/summary.md)
 - [`@template`](./tags/template.md)
 - [`@throws`](./tags/throws.md)

site/tags/sortStrategy.md

@@ -0,0 +1,34 @@
+---
+title: "@sortStrategy"
+---
+
+# @sortStrategy
+
+**Tag Kind:** [Block](../tags.md#Block-tags) <br>
+
+This tag can be used to override the [sort](../options/organization.md#sort) locally
+for a module, namespace, class, or interface. The override will be applied to direct
+children of the declaration it appears on. If the declaration has a child which contains
+children (e.g. a nested namespace) the grandchildren will _not_ be sorted according
+to the `@sortStrategy` tag.
+
+## Example
+
+This class makes the most sense if the documentation is reviewed in the source order
+rather than being sorted alphabetically.
+
+```ts
+/**
+ * @sortStrategy source-order
+ */
+export class Class {
+    commonMethod(): void;
+    commonMethod2(): void;
+    lessCommonMethod(): void;
+    uncommonMethod(): void;
+}
+```
+
+## See Also
+
+- The [`--sort`](../options/organization.md#sort) option

src/lib/converter/plugins/CategoryPlugin.ts

@@ -15,14 +15,15 @@ import type { Context } from "../context.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
 import { i18n } from "#utils";
+import { isValidSortStrategy } from "../../utils/sort.js";
 
 /**
  * A handler that sorts and categorizes the found reflections in the resolving phase.
  *
  * The handler sets the ´category´ property of all reflections.
  */
 export class CategoryPlugin extends ConverterComponent {
-    sortFunction!: (
+    defaultSortFunction!: (
         reflections: Array<DeclarationReflection | DocumentReflection>,
     ) => void;
 
@@ -71,7 +72,7 @@ export class CategoryPlugin extends ConverterComponent {
      * Triggered when the converter begins converting a project.
      */
     private setup() {
-        this.sortFunction = getSortFunction(this.application.options);
+        this.defaultSortFunction = getSortFunction(this.application.options);
 
         // Set up static properties
         if (this.defaultCategory) {
@@ -203,12 +204,25 @@ export class CategoryPlugin extends ConverterComponent {
         }
 
         for (const cat of categories.values()) {
-            this.sortFunction(cat.children);
+            this.getSortFunction(parent)(cat.children);
         }
 
         return Array.from(categories.values());
     }
 
+    getSortFunction(reflection: ContainerReflection) {
+        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.
      *

src/lib/converter/plugins/GroupPlugin.ts

@@ -9,14 +9,14 @@ import {
 import { ReflectionGroup } from "../../models/ReflectionGroup.js";
 import { ConverterComponent } from "../components.js";
 import type { Context } from "../context.js";
-import { getSortFunction } from "../../utils/sort.js";
-import { Option } from "../../utils/index.js";
+import { getSortFunction, isValidSortStrategy, SORT_STRATEGIES } from "../../utils/sort.js";
+import { Option, type SortStrategy } from "../../utils/index.js";
 import { Comment } from "../../models/index.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.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 = [
@@ -47,7 +47,7 @@ const defaultGroupOrder = [
  * The handler sets the `groups` property of all container reflections.
  */
 export class GroupPlugin extends ConverterComponent {
-    sortFunction!: (
+    defaultSortFunction!: (
         reflections: Array<DeclarationReflection | DocumentReflection>,
     ) => void;
 
@@ -107,27 +107,29 @@ export class GroupPlugin extends ConverterComponent {
     }
 
     private 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));
         }
     }
 
     private group(reflection: ContainerReflection) {
+        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")) {
@@ -256,6 +258,25 @@ export class GroupPlugin extends ConverterComponent {
         return Array.from(groups.values()).sort(GroupPlugin.sortGroupCallback);
     }
 
+    getSortFunction(reflection: ContainerReflection) {
+        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 as SortStrategy[]);
+        }
+
+        return this.defaultSortFunction;
+    }
+
     /**
      * Callback used to sort groups by name.
      */

src/lib/internationalization/locales/en.cts

@@ -123,6 +123,8 @@ export = {
         `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:
@@ -419,7 +421,7 @@ export = {
     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}`,
+        `{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.`,

src/lib/utils/options/sources/typedoc.ts

@@ -845,10 +845,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         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(

src/lib/utils/options/tsdoc-defaults.ts

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

src/lib/utils/sort.ts

@@ -163,7 +163,11 @@ const sorts: Record<
     },
 };
 
-export function getSortFunction(opts: Options) {
+export function isValidSortStrategy(strategy: string): strategy is SortStrategy {
+    return SORT_STRATEGIES.includes(strategy as never);
+}
+
+export function getSortFunction(opts: Options, strategies: readonly SortStrategy[] = opts.getValue("sort")) {
     const kindSortOrder = opts
         .getValue("kindSortOrder")
         .map((k) => ReflectionKind[k]);
@@ -174,7 +178,6 @@ export function getSortFunction(opts: Options) {
         }
     }
 
-    const strategies = opts.getValue("sort");
     const data = { kindSortOrder };
 
     return function sortReflections(

src/test/behavior.c2.test.ts

@@ -1486,4 +1486,46 @@ describe("Behavior Tests", () => {
             { kind: "text", text: ")" },
         ]);
     });
+
+    it("Supports the @sortStrategy tag #2965", () => {
+        const project = convert("sortStrategyTag");
+
+        const getOrder = (name: string) => query(project, name).children?.map(c => c.name);
+
+        equal(getOrder("A"), ["b", "c", "a"]);
+        equal(getOrder("B"), ["a", "b", "c"]);
+        equal(getOrder("C"), ["b", "c", "a"]);
+
+        const getGroupOrders = (name: string) =>
+            query(project, name).groups?.map(g => [g.title, g.children.map(c => c.name)]);
+
+        equal(getGroupOrders("A"), [
+            ["Variables", ["b", "a"]],
+            ["Functions", ["c"]],
+        ]);
+
+        equal(getGroupOrders("B"), [
+            ["Variables", ["a", "b"]],
+            ["Functions", ["c"]],
+        ]);
+
+        equal(getGroupOrders("C"), [
+            ["Variables", ["b", "c"]],
+            ["Functions", ["a"]],
+        ]);
+
+        const getCategoryOrders = (name: string) =>
+            query(project, name).categories?.map(g => [g.title, g.children.map(c => c.name)]);
+
+        equal(getCategoryOrders("D"), [
+            ["Cat", ["b", "a", "c"]],
+        ]);
+
+        logger.expectMessage(
+            `warn: Comment for E specifies @sortStrategy with "invalid", which is an invalid sort strategy*`,
+        );
+        logger.expectMessage(
+            `warn: Comment for E specifies @sortStrategy with "invalid2", which is an invalid sort strategy*`,
+        );
+    });
 });

src/test/converter2/behavior/sortStrategyTag.ts

@@ -0,0 +1,33 @@
+/** @sortStrategy source-order */
+export namespace A {
+    export const b = 1;
+    export function c() {}
+    export const a = 2;
+}
+
+/** @sortStrategy alphabetical */
+export namespace B {
+    export function c() {}
+    export const b = 1;
+    export const a = 1;
+}
+
+// Default is kind then alphabetical
+export namespace C {
+    export const c = 1;
+    export function a() {}
+    export const b = 1;
+}
+
+/** @sortStrategy source-order */
+export namespace D {
+    /** @category Cat */
+    export const b = 1;
+    /** @category Cat */
+    export const a = 1;
+    /** @category Cat */
+    export const c = 1;
+}
+
+/** @sortStrategy invalid, source-order, invalid2 */
+export namespace E {}

tsdoc.json

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