typedoc 0.23.21 → 0.23.22

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

@@ -1,7 +1,6 @@
 import { ReflectionKind, DeclarationReflection } from "../../models/reflections/index";
 import { ReflectionGroup } from "../../models/ReflectionGroup";
 import { ConverterComponent } from "../components";
-import { SortStrategy } from "../../utils/sort";
 /**
  * A handler that sorts and groups the found reflections in the resolving phase.
  *
@@ -25,8 +24,7 @@ export declare class GroupPlugin extends ConverterComponent {
         16: string;
         4194304: string;
     };
-    /** @internal */
-    sortStrategies: SortStrategy[];
+    sortFunction: (reflections: DeclarationReflection[]) => void;
     boosts: Record<string, number>;
     usedBoosts: Set<string>;
     /**

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

@@ -30,6 +30,9 @@ let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.Convert
      */
     initialize() {
         this.listenTo(this.owner, {
+            [converter_1.Converter.EVENT_RESOLVE_BEGIN]: () => {
+                this.sortFunction = (0, sort_1.getSortFunction)(this.application.options);
+            },
             [converter_1.Converter.EVENT_RESOLVE]: this.onResolve,
             [converter_1.Converter.EVENT_RESOLVE_END]: this.onEndResolve,
         });
@@ -68,7 +71,7 @@ let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.Convert
         if (reflection.children &&
             reflection.children.length > 0 &&
             !reflection.groups) {
-            (0, sort_1.sortReflections)(reflection.children, this.sortStrategies);
+            this.sortFunction(reflection.children);
             reflection.groups = this.getReflectionGroups(reflection.children);
         }
     }
@@ -193,9 +196,6 @@ GroupPlugin.PLURALS = {
     [index_1.ReflectionKind.EnumMember]: "Enumeration Members",
     [index_1.ReflectionKind.TypeAlias]: "Type Aliases",
 };
-__decorate([
-    (0, utils_1.BindOption)("sort")
-], GroupPlugin.prototype, "sortStrategies", void 0);
 __decorate([
     (0, utils_1.BindOption)("searchGroupBoosts")
 ], GroupPlugin.prototype, "boosts", void 0);

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

@@ -16,6 +16,7 @@ const fs_1 = require("../../utils/fs");
 const path_1 = require("path");
 const models_1 = require("../../models");
 const repository_1 = require("../utils/repository");
+const base_path_1 = require("../utils/base-path");
 /**
  * A handler that attaches source file information to reflections.
  */
@@ -64,7 +65,7 @@ let SourcePlugin = class SourcePlugin extends components_1.ConverterComponent {
         const symbol = reflection.project.getSymbolFromReflection(reflection);
         for (const node of symbol?.declarations || []) {
             const sourceFile = node.getSourceFile();
-            const fileName = sourceFile.fileName;
+            const fileName = base_path_1.BasePath.normalize(sourceFile.fileName);
             this.fileNames.add(fileName);
             let position;
             if ((0, nodes_1.isNamedNode)(node)) {
@@ -81,7 +82,7 @@ let SourcePlugin = class SourcePlugin extends components_1.ConverterComponent {
         if (this.disableSources || !sig)
             return;
         const sourceFile = sig.getSourceFile();
-        const fileName = sourceFile.fileName;
+        const fileName = base_path_1.BasePath.normalize(sourceFile.fileName);
         this.fileNames.add(fileName);
         const position = ts.getLineAndCharacterOfPosition(sourceFile, sig.getStart());
         reflection.sources || (reflection.sources = []);

package/dist/lib/converter/utils/base-path.js

@@ -82,7 +82,7 @@ class BasePath {
         path = path.replace(/\\/g, "/");
         // Remove all surrounding quotes
         path = path.replace(/^["']+|["']+$/g, "");
-        // Make Windows drive letters lower case
+        // Make Windows drive letters upper case
         return path.replace(/^([^:]+):\//, (_m, m1) => m1.toUpperCase() + ":/");
     }
 }

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

@@ -100,8 +100,8 @@ function displayPartsToMarkdown(parts, urlTo) {
                     case "@linkplain": {
                         if (part.target) {
                             const url = typeof part.target === "string" ? part.target : urlTo(part.target);
-                            const wrap = part.tag === "@linkcode" ? "`" : "";
-                            result.push(url ? `[${wrap}${part.text}${wrap}](${url})` : part.text);
+                            const text = part.tag === "@linkcode" ? `<code>${part.text}</code>` : part.text;
+                            result.push(url ? `<a href="${url}">${text}</a>` : part.text);
                         }
                         else {
                             result.push(part.text);

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

@@ -2,3 +2,4 @@ export declare function getEnumFlags<T extends number>(flags: T): T[];
 export declare function removeFlag<T extends number>(flag: T, remove: T & {}): T;
 export declare function hasAllFlags(flags: number, check: number): boolean;
 export declare function hasAnyFlag(flags: number, check: number): boolean;
+export declare function getEnumKeys(Enum: Record<string, string | number>): string[];

package/dist/lib/utils/enum.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasAnyFlag = exports.hasAllFlags = exports.removeFlag = exports.getEnumFlags = void 0;
+exports.getEnumKeys = exports.hasAnyFlag = exports.hasAllFlags = exports.removeFlag = exports.getEnumFlags = void 0;
 function getEnumFlags(flags) {
     const result = [];
     for (let i = 1; i <= flags; i <<= 1) {
@@ -24,3 +24,10 @@ function hasAnyFlag(flags, check) {
     return (flags & check) !== 0;
 }
 exports.hasAnyFlag = hasAnyFlag;
+// Note: String enums are not handled.
+function getEnumKeys(Enum) {
+    return Object.keys(Enum).filter((k) => {
+        return Enum[Enum[k]] === k;
+    });
+}
+exports.getEnumKeys = getEnumKeys;

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

@@ -9,7 +9,7 @@ export { DefaultMap } from "./map";
 export { ArgumentsReader, BindOption, CommentStyle, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, } from "./options";
 export type { ArrayDeclarationOption, BooleanDeclarationOption, DeclarationOption, DeclarationOptionBase, DeclarationOptionToOptionType, KeyToDeclaration, MapDeclarationOption, MixedDeclarationOption, NumberDeclarationOption, FlagsDeclarationOption, ObjectDeclarationOption, OptionsReader, StringDeclarationOption, TypeDocOptionMap, TypeDocOptions, ValidationOptions, TypeDocOptionValues, ParameterTypeToOptionTypeMap, ManuallyValidatedOption, } from "./options";
 export { discoverPlugins, loadPlugins } from "./plugins";
-export { sortReflections } from "./sort";
+export { getSortFunction } from "./sort";
 export type { SortStrategy } from "./sort";
 export { EventHooks } from "./hooks";
 export * from "./entry-point";

package/dist/lib/utils/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MinimalSourceFile = exports.Validation = exports.renderElement = exports.Raw = exports.Fragment = exports.JSX = exports.EventHooks = exports.sortReflections = exports.loadPlugins = exports.discoverPlugins = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.DefaultMap = exports.LogLevel = exports.Logger = exports.ConsoleLogger = exports.CallbackLogger = exports.assertNever = exports.writeFileSync = exports.writeFile = exports.readFile = exports.normalizePath = exports.getCommonDirectory = exports.copySync = exports.copy = exports.EventDispatcher = exports.Event = exports.Component = exports.ChildableComponent = exports.AbstractComponent = exports.unique = exports.removeIfPresent = exports.removeIf = exports.partition = exports.insertPrioritySorted = exports.filterMap = void 0;
+exports.MinimalSourceFile = exports.Validation = exports.renderElement = exports.Raw = exports.Fragment = exports.JSX = exports.EventHooks = exports.getSortFunction = exports.loadPlugins = exports.discoverPlugins = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.DefaultMap = exports.LogLevel = exports.Logger = exports.ConsoleLogger = exports.CallbackLogger = exports.assertNever = exports.writeFileSync = exports.writeFile = exports.readFile = exports.normalizePath = exports.getCommonDirectory = exports.copySync = exports.copy = exports.EventDispatcher = exports.Event = exports.Component = exports.ChildableComponent = exports.AbstractComponent = exports.unique = exports.removeIfPresent = exports.removeIf = exports.partition = exports.insertPrioritySorted = exports.filterMap = void 0;
 var array_1 = require("./array");
 Object.defineProperty(exports, "filterMap", { enumerable: true, get: function () { return array_1.filterMap; } });
 Object.defineProperty(exports, "insertPrioritySorted", { enumerable: true, get: function () { return array_1.insertPrioritySorted; } });
@@ -59,7 +59,7 @@ var plugins_1 = require("./plugins");
 Object.defineProperty(exports, "discoverPlugins", { enumerable: true, get: function () { return plugins_1.discoverPlugins; } });
 Object.defineProperty(exports, "loadPlugins", { enumerable: true, get: function () { return plugins_1.loadPlugins; } });
 var sort_1 = require("./sort");
-Object.defineProperty(exports, "sortReflections", { enumerable: true, get: function () { return sort_1.sortReflections; } });
+Object.defineProperty(exports, "getSortFunction", { enumerable: true, get: function () { return sort_1.getSortFunction; } });
 var hooks_1 = require("./hooks");
 Object.defineProperty(exports, "EventHooks", { enumerable: true, get: function () { return hooks_1.EventHooks; } });
 __exportStar(require("./entry-point"), exports);

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

@@ -94,6 +94,7 @@ export interface TypeDocOptionMap {
     defaultCategory: string;
     categoryOrder: string[];
     sort: SortStrategy[];
+    kindSortOrder: Array<keyof typeof ReflectionKind>;
     visibilityFilters: ManuallyValidatedOption<{
         protected?: boolean;
         private?: boolean;

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

@@ -9,6 +9,7 @@ const entry_point_1 = require("../../entry-point");
 const kind_1 = require("../../../models/reflections/kind");
 const Validation = require("../../validation");
 const tsdoc_defaults_1 = require("../tsdoc-defaults");
+const enum_1 = require("../../enum");
 // For convenience, added in the same order as they are documented on the website.
 function addTypeDocOptions(options) {
     ///////////////////////////
@@ -390,6 +391,22 @@ function addTypeDocOptions(options) {
             }
         },
     });
+    options.addDeclaration({
+        name: "kindSortOrder",
+        help: "Specify the sort order for reflections when 'kind' is specified.",
+        type: declaration_1.ParameterType.Array,
+        defaultValue: [],
+        validate(value) {
+            const invalid = new Set(value);
+            const valid = (0, enum_1.getEnumKeys)(kind_1.ReflectionKind);
+            for (const v of valid) {
+                invalid.delete(v);
+            }
+            if (invalid.size !== 0) {
+                throw new Error(`kindSortOrder may only specify known values, and invalid values were provided (${Array.from(invalid).join(", ")}). The valid kinds are:\n${valid.join(", ")}`);
+            }
+        },
+    });
     options.addDeclaration({
         name: "visibilityFilters",
         help: "Specify the default visibility for builtin filters and additional filters according to modifier tags.",
@@ -511,7 +528,7 @@ function addTypeDocOptions(options) {
         type: declaration_1.ParameterType.Array,
         validate(values) {
             // this is good enough because the values of the ReflectionKind enum are all numbers
-            const validValues = Object.values(kind_1.ReflectionKind).filter((v) => typeof v === "string");
+            const validValues = (0, enum_1.getEnumKeys)(kind_1.ReflectionKind);
             for (const kind of values) {
                 if (!validValues.includes(kind)) {
                     throw new Error(`'${kind}' is an invalid value for 'requiredToBeDocumented'. Must be one of: ${validValues.join(", ")}`);

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

@@ -3,6 +3,7 @@
  * @module
  */
 import type { DeclarationReflection } from "../models/reflections/declaration";
+import type { Options } from "./options";
 export declare const SORT_STRATEGIES: readonly ["source-order", "alphabetical", "enum-value-ascending", "enum-value-descending", "static-first", "instance-first", "visibility", "required-first", "kind"];
 export type SortStrategy = typeof SORT_STRATEGIES[number];
-export declare function sortReflections(reflections: DeclarationReflection[], strategies: readonly SortStrategy[]): void;
+export declare function getSortFunction(opts: Options): (reflections: DeclarationReflection[]) => void;

package/dist/lib/utils/sort.js

@@ -4,7 +4,7 @@
  * @module
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sortReflections = exports.SORT_STRATEGIES = void 0;
+exports.getSortFunction = exports.SORT_STRATEGIES = void 0;
 const kind_1 = require("../models/reflections/kind");
 const types_1 = require("../models/types");
 exports.SORT_STRATEGIES = [
@@ -18,6 +18,32 @@ exports.SORT_STRATEGIES = [
     "required-first",
     "kind",
 ];
+const defaultKindSortOrder = [
+    kind_1.ReflectionKind.Reference,
+    kind_1.ReflectionKind.Project,
+    kind_1.ReflectionKind.Module,
+    kind_1.ReflectionKind.Namespace,
+    kind_1.ReflectionKind.Enum,
+    kind_1.ReflectionKind.EnumMember,
+    kind_1.ReflectionKind.Class,
+    kind_1.ReflectionKind.Interface,
+    kind_1.ReflectionKind.TypeAlias,
+    kind_1.ReflectionKind.Constructor,
+    kind_1.ReflectionKind.Property,
+    kind_1.ReflectionKind.Variable,
+    kind_1.ReflectionKind.Function,
+    kind_1.ReflectionKind.Accessor,
+    kind_1.ReflectionKind.Method,
+    kind_1.ReflectionKind.ObjectLiteral,
+    kind_1.ReflectionKind.Parameter,
+    kind_1.ReflectionKind.TypeParameter,
+    kind_1.ReflectionKind.TypeLiteral,
+    kind_1.ReflectionKind.CallSignature,
+    kind_1.ReflectionKind.ConstructorSignature,
+    kind_1.ReflectionKind.IndexSignature,
+    kind_1.ReflectionKind.GetSignature,
+    kind_1.ReflectionKind.SetSignature,
+];
 // Return true if a < b
 const sorts = {
     "source-order"(a, b) {
@@ -87,47 +113,33 @@ const sorts = {
     "required-first"(a, b) {
         return !a.flags.isOptional && b.flags.isOptional;
     },
-    kind(a, b) {
-        const weights = [
-            kind_1.ReflectionKind.Reference,
-            kind_1.ReflectionKind.Project,
-            kind_1.ReflectionKind.Module,
-            kind_1.ReflectionKind.Namespace,
-            kind_1.ReflectionKind.Enum,
-            kind_1.ReflectionKind.EnumMember,
-            kind_1.ReflectionKind.Class,
-            kind_1.ReflectionKind.Interface,
-            kind_1.ReflectionKind.TypeAlias,
-            kind_1.ReflectionKind.Constructor,
-            kind_1.ReflectionKind.Property,
-            kind_1.ReflectionKind.Variable,
-            kind_1.ReflectionKind.Function,
-            kind_1.ReflectionKind.Accessor,
-            kind_1.ReflectionKind.Method,
-            kind_1.ReflectionKind.ObjectLiteral,
-            kind_1.ReflectionKind.Parameter,
-            kind_1.ReflectionKind.TypeParameter,
-            kind_1.ReflectionKind.TypeLiteral,
-            kind_1.ReflectionKind.CallSignature,
-            kind_1.ReflectionKind.ConstructorSignature,
-            kind_1.ReflectionKind.IndexSignature,
-            kind_1.ReflectionKind.GetSignature,
-            kind_1.ReflectionKind.SetSignature,
-        ];
-        return weights.indexOf(a.kind) < weights.indexOf(b.kind);
+    kind(a, b, { kindSortOrder }) {
+        return kindSortOrder.indexOf(a.kind) < kindSortOrder.indexOf(b.kind);
     },
 };
-function sortReflections(reflections, strategies) {
-    reflections.sort((a, b) => {
-        for (const s of strategies) {
-            if (sorts[s](a, b)) {
-                return -1;
-            }
-            if (sorts[s](b, a)) {
-                return 1;
-            }
+function getSortFunction(opts) {
+    const kindSortOrder = opts
+        .getValue("kindSortOrder")
+        .map((k) => kind_1.ReflectionKind[k]);
+    for (const kind of defaultKindSortOrder) {
+        if (!kindSortOrder.includes(kind)) {
+            kindSortOrder.push(kind);
         }
-        return 0;
-    });
+    }
+    const strategies = opts.getValue("sort");
+    const data = { kindSortOrder };
+    return function sortReflections(reflections) {
+        reflections.sort((a, b) => {
+            for (const s of strategies) {
+                if (sorts[s](a, b, data)) {
+                    return -1;
+                }
+                if (sorts[s](b, a, data)) {
+                    return 1;
+                }
+            }
+            return 0;
+        });
+    };
 }
-exports.sortReflections = sortReflections;
+exports.getSortFunction = getSortFunction;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.23.21",
+  "version": "0.23.22",
   "homepage": "https://typedoc.org",
   "main": "./dist/index.js",
   "exports": {