typedoc 0.25.7 → 0.25.9

package/dist/index.d.ts

@@ -3,6 +3,13 @@ export { EventDispatcher, Event } from "./lib/utils/events";
 export { resetReflectionID } from "./lib/models/reflections/abstract";
 /**
  * All symbols documented under the Models namespace are also available in the root import.
+ *
+ * @categoryDescription Types
+ * Describes a TypeScript type.
+ *
+ * @categoryDescription Reflections
+ * Describes a documentation entry. The root entry is a {@link ProjectReflection}
+ * and contains {@link DeclarationReflection} instances.
  */
 export * as Models from "./lib/models";
 /**

package/dist/index.js

@@ -39,6 +39,13 @@ var abstract_1 = require("./lib/models/reflections/abstract");
 Object.defineProperty(exports, "resetReflectionID", { enumerable: true, get: function () { return abstract_1.resetReflectionID; } });
 /**
  * All symbols documented under the Models namespace are also available in the root import.
+ *
+ * @categoryDescription Types
+ * Describes a TypeScript type.
+ *
+ * @categoryDescription Reflections
+ * Describes a documentation entry. The root entry is a {@link ProjectReflection}
+ * and contains {@link DeclarationReflection} instances.
  */
 exports.Models = __importStar(require("./lib/models"));
 /**

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

@@ -12,5 +12,6 @@ export declare function discoverFileComment(node: ts.SourceFile, commentStyle: C
     ranges: ts.CommentRange[];
     jsDoc: ts.JSDoc | undefined;
 } | undefined;
+export declare function discoverNodeComment(node: ts.Node, commentStyle: CommentStyle): DiscoveredComment | undefined;
 export declare function discoverComment(symbol: ts.Symbol, kind: ReflectionKind, logger: Logger, commentStyle: CommentStyle): DiscoveredComment | undefined;
 export declare function discoverSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, commentStyle: CommentStyle): DiscoveredComment | undefined;

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.discoverSignatureComment = exports.discoverComment = exports.discoverFileComment = void 0;
+exports.discoverSignatureComment = exports.discoverComment = exports.discoverNodeComment = exports.discoverFileComment = void 0;
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../../models");
 const utils_1 = require("../../utils");
@@ -69,6 +69,10 @@ const wantedKinds = {
     [models_1.ReflectionKind.Class]: [
         typescript_1.default.SyntaxKind.ClassDeclaration,
         typescript_1.default.SyntaxKind.BindingElement,
+        // If marked with @class
+        typescript_1.default.SyntaxKind.VariableDeclaration,
+        typescript_1.default.SyntaxKind.ExportAssignment,
+        typescript_1.default.SyntaxKind.FunctionDeclaration,
     ],
     [models_1.ReflectionKind.Interface]: [
         typescript_1.default.SyntaxKind.InterfaceDeclaration,
@@ -116,6 +120,20 @@ function discoverFileComment(node, commentStyle) {
     }
 }
 exports.discoverFileComment = discoverFileComment;
+function discoverNodeComment(node, commentStyle) {
+    const text = node.getSourceFile().text;
+    const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
+    comments.reverse();
+    const selectedDocComment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
+    if (selectedDocComment) {
+        return {
+            file: node.getSourceFile(),
+            ranges: selectedDocComment,
+            jsDoc: findJsDocForComment(node, selectedDocComment),
+        };
+    }
+}
+exports.discoverNodeComment = discoverNodeComment;
 function discoverComment(symbol, kind, logger, commentStyle) {
     // For a module comment, we want the first one defined in the file,
     // not the last one, since that will apply to the import or declaration.

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

@@ -10,6 +10,7 @@ export interface CommentParserConfig {
 }
 export declare function clearCommentCache(): void;
 export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
+export declare function getNodeComment(node: ts.Node, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
 export declare function getFileComment(file: ts.SourceFile, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
 export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
 export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined): Comment | undefined;

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getJsDocComment = exports.getSignatureComment = exports.getFileComment = exports.getComment = exports.clearCommentCache = void 0;
+exports.getJsDocComment = exports.getSignatureComment = exports.getFileComment = exports.getNodeComment = exports.getComment = exports.clearCommentCache = void 0;
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../../models");
 const utils_1 = require("../../utils");
@@ -89,6 +89,10 @@ function getComment(symbol, kind, config, logger, commentStyle, checker) {
     return comment;
 }
 exports.getComment = getComment;
+function getNodeComment(node, kind, config, logger, commentStyle, checker) {
+    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, kind === models_1.ReflectionKind.Module, checker);
+}
+exports.getNodeComment = getNodeComment;
 function getFileComment(file, config, logger, commentStyle, checker) {
     return getCommentImpl((0, discovery_1.discoverFileComment)(file, commentStyle), config, logger, 
     /* moduleComment */ true, checker);

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

@@ -79,6 +79,7 @@ export declare class Context {
     /** @internal */
     setActiveProgram(program: ts.Program | undefined): void;
     getComment(symbol: ts.Symbol, kind: ReflectionKind): import("../models/index").Comment | undefined;
+    getNodeComment(node: ts.Node, kind: ReflectionKind): import("../models/index").Comment | undefined;
     getFileComment(node: ts.SourceFile): import("../models/index").Comment | undefined;
     getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag): import("../models/index").Comment | undefined;
     getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): import("../models/index").Comment | undefined;

package/dist/lib/converter/context.js

@@ -175,6 +175,9 @@ class Context {
     getComment(symbol, kind) {
         return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
     }
+    getNodeComment(node, kind) {
+        return (0, comments_1.getNodeComment)(node, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
+    }
     getFileComment(node) {
         return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
     }

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

@@ -38,6 +38,8 @@ export declare class Converter extends ChildableComponent<Application, Converter
     accessor useTsLinkResolution: boolean;
     /** @internal */
     accessor preserveLinkText: boolean;
+    /** @internal */
+    accessor maxTypeConversionDepth: number;
     private _config?;
     private _externalSymbolResolvers;
     get config(): CommentParserConfig;

package/dist/lib/converter/converter.js

@@ -71,7 +71,7 @@ const linkResolver_1 = require("./comments/linkResolver");
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
 let Converter = (() => {
-    var _Converter_externalPattern_accessor_storage, _Converter_excludeExternals_accessor_storage, _Converter_excludeNotDocumented_accessor_storage, _Converter_excludePrivate_accessor_storage, _Converter_excludeProtected_accessor_storage, _Converter_excludeReferences_accessor_storage, _Converter_commentStyle_accessor_storage, _Converter_validation_accessor_storage, _Converter_externalSymbolLinkMappings_accessor_storage, _Converter_useTsLinkResolution_accessor_storage, _Converter_preserveLinkText_accessor_storage;
+    var _Converter_externalPattern_accessor_storage, _Converter_excludeExternals_accessor_storage, _Converter_excludeNotDocumented_accessor_storage, _Converter_excludePrivate_accessor_storage, _Converter_excludeProtected_accessor_storage, _Converter_excludeReferences_accessor_storage, _Converter_commentStyle_accessor_storage, _Converter_validation_accessor_storage, _Converter_externalSymbolLinkMappings_accessor_storage, _Converter_useTsLinkResolution_accessor_storage, _Converter_preserveLinkText_accessor_storage, _Converter_maxTypeConversionDepth_accessor_storage;
     let _classDecorators = [(0, component_1.Component)({
             name: "converter",
             internal: true,
@@ -104,6 +104,8 @@ let Converter = (() => {
     let _useTsLinkResolution_initializers = [];
     let _preserveLinkText_decorators;
     let _preserveLinkText_initializers = [];
+    let _maxTypeConversionDepth_decorators;
+    let _maxTypeConversionDepth_initializers = [];
     var Converter = _classThis = class extends _classSuper {
         /** @internal */
         get externalPattern() { return __classPrivateFieldGet(this, _Converter_externalPattern_accessor_storage, "f"); }
@@ -138,6 +140,9 @@ let Converter = (() => {
         /** @internal */
         get preserveLinkText() { return __classPrivateFieldGet(this, _Converter_preserveLinkText_accessor_storage, "f"); }
         set preserveLinkText(value) { __classPrivateFieldSet(this, _Converter_preserveLinkText_accessor_storage, value, "f"); }
+        /** @internal */
+        get maxTypeConversionDepth() { return __classPrivateFieldGet(this, _Converter_maxTypeConversionDepth_accessor_storage, "f"); }
+        set maxTypeConversionDepth(value) { __classPrivateFieldSet(this, _Converter_maxTypeConversionDepth_accessor_storage, value, "f"); }
         get config() {
             return this._config || this._buildCommentParserConfig();
         }
@@ -154,6 +159,7 @@ let Converter = (() => {
             _Converter_externalSymbolLinkMappings_accessor_storage.set(this, __runInitializers(this, _externalSymbolLinkMappings_initializers, void 0));
             _Converter_useTsLinkResolution_accessor_storage.set(this, __runInitializers(this, _useTsLinkResolution_initializers, void 0));
             _Converter_preserveLinkText_accessor_storage.set(this, __runInitializers(this, _preserveLinkText_initializers, void 0));
+            _Converter_maxTypeConversionDepth_accessor_storage.set(this, __runInitializers(this, _maxTypeConversionDepth_initializers, void 0));
             this._externalSymbolResolvers = [];
             this.addUnknownSymbolResolver((ref) => {
                 // Require global links, matching local ones will likely hide mistakes where the
@@ -184,7 +190,7 @@ let Converter = (() => {
          * Compile the given source files and create a project reflection for them.
          */
         convert(entryPoints) {
-            const programs = entryPoints.map((e) => e.program);
+            const programs = (0, utils_1.unique)(entryPoints.map((e) => e.program));
             this.externalPatternCache = void 0;
             const project = new index_1.ProjectReflection(this.application.options.getValue("name"));
             const context = new context_1.Context(this, programs, project);
@@ -378,6 +384,7 @@ let Converter = (() => {
     _Converter_externalSymbolLinkMappings_accessor_storage = new WeakMap();
     _Converter_useTsLinkResolution_accessor_storage = new WeakMap();
     _Converter_preserveLinkText_accessor_storage = new WeakMap();
+    _Converter_maxTypeConversionDepth_accessor_storage = new WeakMap();
     __setFunctionName(_classThis, "Converter");
     (() => {
         const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -392,6 +399,7 @@ let Converter = (() => {
         _externalSymbolLinkMappings_decorators = [(0, utils_1.Option)("externalSymbolLinkMappings")];
         _useTsLinkResolution_decorators = [(0, utils_1.Option)("useTsLinkResolution")];
         _preserveLinkText_decorators = [(0, utils_1.Option)("preserveLinkText")];
+        _maxTypeConversionDepth_decorators = [(0, utils_1.Option)("maxTypeConversionDepth")];
         __esDecorate(_classThis, null, _externalPattern_decorators, { kind: "accessor", name: "externalPattern", static: false, private: false, access: { has: obj => "externalPattern" in obj, get: obj => obj.externalPattern, set: (obj, value) => { obj.externalPattern = value; } }, metadata: _metadata }, _externalPattern_initializers, _instanceExtraInitializers);
         __esDecorate(_classThis, null, _excludeExternals_decorators, { kind: "accessor", name: "excludeExternals", static: false, private: false, access: { has: obj => "excludeExternals" in obj, get: obj => obj.excludeExternals, set: (obj, value) => { obj.excludeExternals = value; } }, metadata: _metadata }, _excludeExternals_initializers, _instanceExtraInitializers);
         __esDecorate(_classThis, null, _excludeNotDocumented_decorators, { kind: "accessor", name: "excludeNotDocumented", static: false, private: false, access: { has: obj => "excludeNotDocumented" in obj, get: obj => obj.excludeNotDocumented, set: (obj, value) => { obj.excludeNotDocumented = value; } }, metadata: _metadata }, _excludeNotDocumented_initializers, _instanceExtraInitializers);
@@ -403,6 +411,7 @@ let Converter = (() => {
         __esDecorate(_classThis, null, _externalSymbolLinkMappings_decorators, { kind: "accessor", name: "externalSymbolLinkMappings", static: false, private: false, access: { has: obj => "externalSymbolLinkMappings" in obj, get: obj => obj.externalSymbolLinkMappings, set: (obj, value) => { obj.externalSymbolLinkMappings = value; } }, metadata: _metadata }, _externalSymbolLinkMappings_initializers, _instanceExtraInitializers);
         __esDecorate(_classThis, null, _useTsLinkResolution_decorators, { kind: "accessor", name: "useTsLinkResolution", static: false, private: false, access: { has: obj => "useTsLinkResolution" in obj, get: obj => obj.useTsLinkResolution, set: (obj, value) => { obj.useTsLinkResolution = value; } }, metadata: _metadata }, _useTsLinkResolution_initializers, _instanceExtraInitializers);
         __esDecorate(_classThis, null, _preserveLinkText_decorators, { kind: "accessor", name: "preserveLinkText", static: false, private: false, access: { has: obj => "preserveLinkText" in obj, get: obj => obj.preserveLinkText, set: (obj, value) => { obj.preserveLinkText = value; } }, metadata: _metadata }, _preserveLinkText_initializers, _instanceExtraInitializers);
+        __esDecorate(_classThis, null, _maxTypeConversionDepth_decorators, { kind: "accessor", name: "maxTypeConversionDepth", static: false, private: false, access: { has: obj => "maxTypeConversionDepth" in obj, get: obj => obj.maxTypeConversionDepth, set: (obj, value) => { obj.maxTypeConversionDepth = value; } }, metadata: _metadata }, _maxTypeConversionDepth_initializers, _instanceExtraInitializers);
         __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
         Converter = _classThis = _classDescriptor.value;
         if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });

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

@@ -1,7 +1,11 @@
 import ts from "typescript";
-import { ParameterReflection, ReflectionKind, SignatureReflection, TypeParameterReflection } from "../../models";
+import { ParameterReflection, Reflection, ReflectionKind, SignatureReflection, TypeParameterReflection } from "../../models";
 import type { Context } from "../context";
 export declare function createSignature(context: Context, kind: ReflectionKind.CallSignature | ReflectionKind.ConstructorSignature | ReflectionKind.GetSignature | ReflectionKind.SetSignature, signature: ts.Signature, symbol: ts.Symbol | undefined, declaration?: ts.SignatureDeclaration | ts.JSDocSignature): void;
+/**
+ * Special cased constructor factory for functions tagged with `@class`
+ */
+export declare function createConstructSignatureWithType(context: Context, signature: ts.Signature, classType: Reflection): void;
 export declare function convertParameterNodes(context: Context, sigRef: SignatureReflection, parameters: readonly (ts.JSDocParameterTag | ts.ParameterDeclaration)[]): ParameterReflection[];
 export declare function convertTypeParameterNodes(context: Context, parameters: readonly ts.TypeParameterDeclaration[] | undefined): TypeParameterReflection[] | undefined;
 export declare function createTypeParamReflection(param: ts.TypeParameterDeclaration, context: Context): TypeParameterReflection;

package/dist/lib/converter/factories/signature.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertTemplateParameterNodes = exports.createTypeParamReflection = exports.convertTypeParameterNodes = exports.convertParameterNodes = exports.createSignature = void 0;
+exports.convertTemplateParameterNodes = exports.createTypeParamReflection = exports.convertTypeParameterNodes = exports.convertParameterNodes = exports.createConstructSignatureWithType = exports.createSignature = void 0;
 const typescript_1 = __importDefault(require("typescript"));
 const assert_1 = __importDefault(require("assert"));
 const models_1 = require("../../models");
@@ -17,6 +17,11 @@ function createSignature(context, kind, signature, symbol, declaration) {
     const sigRef = new models_1.SignatureReflection(kind == models_1.ReflectionKind.ConstructorSignature
         ? `new ${context.scope.parent.name}`
         : context.scope.name, kind, context.scope);
+    // This feels awful, but we need some way to tell if callable signatures on classes
+    // are "static" (e.g. `Foo()`) or not (e.g. `(new Foo())()`)
+    if (context.shouldBeStatic) {
+        sigRef.setFlag(models_1.ReflectionFlag.Static);
+    }
     const sigRefCtx = context.withScope(sigRef);
     if (symbol && declaration) {
         context.project.registerSymbolId(sigRef, new ReflectionSymbolId_1.ReflectionSymbolId(symbol, declaration));
@@ -72,6 +77,25 @@ function createSignature(context, kind, signature, symbol, declaration) {
     context.converter.trigger(converter_events_1.ConverterEvents.CREATE_SIGNATURE, context, sigRef, declaration, signature);
 }
 exports.createSignature = createSignature;
+/**
+ * Special cased constructor factory for functions tagged with `@class`
+ */
+function createConstructSignatureWithType(context, signature, classType) {
+    (0, assert_1.default)(context.scope instanceof models_1.DeclarationReflection);
+    const declaration = signature.getDeclaration();
+    const sigRef = new models_1.SignatureReflection(`new ${context.scope.parent.name}`, models_1.ReflectionKind.ConstructorSignature, context.scope);
+    const sigRefCtx = context.withScope(sigRef);
+    if (declaration) {
+        sigRef.comment = context.getSignatureComment(declaration);
+    }
+    sigRef.typeParameters = convertTypeParameters(sigRefCtx, sigRef, signature.typeParameters);
+    sigRef.type = models_1.ReferenceType.createResolvedReference(context.scope.parent.name, classType, context.project);
+    context.registerReflection(sigRef, undefined);
+    context.scope.signatures ??= [];
+    context.scope.signatures.push(sigRef);
+    context.converter.trigger(converter_events_1.ConverterEvents.CREATE_SIGNATURE, context, sigRef, declaration, signature);
+}
+exports.createConstructSignatureWithType = createConstructSignatureWithType;
 function convertParameters(context, sigRef, parameters, parameterNodes) {
     return parameters.map((param, i) => {
         const declaration = param.valueDeclaration;

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

@@ -155,7 +155,7 @@ let CategoryPlugin = (() => {
             obj.groups.forEach((group) => {
                 if (group.categories)
                     return;
-                group.categories = this.getReflectionCategories(group.children);
+                group.categories = this.getReflectionCategories(obj, group.children);
                 if (group.categories && group.categories.length > 1) {
                     group.categories.sort(CategoryPlugin.sortCatCallback);
                 }
@@ -170,7 +170,7 @@ let CategoryPlugin = (() => {
             if (!obj.children || obj.children.length === 0 || obj.categories) {
                 return;
             }
-            obj.categories = this.getReflectionCategories(obj.children);
+            obj.categories = this.getReflectionCategories(obj, obj.children);
             if (obj.categories && obj.categories.length > 1) {
                 obj.categories.sort(CategoryPlugin.sortCatCallback);
             }
@@ -188,7 +188,7 @@ let CategoryPlugin = (() => {
          *   relevance boost to be used when searching
          * @returns An array containing all children of the given reflection categorized
          */
-        getReflectionCategories(reflections) {
+        getReflectionCategories(parent, reflections) {
             const categories = new Map();
             for (const child of reflections) {
                 const childCategories = this.extractCategories(child);
@@ -207,6 +207,22 @@ let CategoryPlugin = (() => {
                     }
                 }
             }
+            if (parent.comment) {
+                (0, utils_1.removeIf)(parent.comment.blockTags, (tag) => {
+                    if (tag.tag === "@categoryDescription") {
+                        const { header, body } = models_1.Comment.splitPartsToHeaderAndBody(tag.content);
+                        const cat = categories.get(header);
+                        if (cat) {
+                            cat.description = body;
+                        }
+                        else {
+                            this.application.logger.warn(`Comment for ${parent.getFriendlyFullName()} includes @categoryDescription for "${header}", but no child is placed in that category.`);
+                        }
+                        return true;
+                    }
+                    return false;
+                });
+            }
             for (const cat of categories.values()) {
                 this.sortFunction(cat.children);
             }

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

@@ -1,4 +1,4 @@
-import { DeclarationReflection } from "../../models/reflections/index";
+import { ContainerReflection, DeclarationReflection } from "../../models/reflections/index";
 import { ReflectionGroup } from "../../models/ReflectionGroup";
 import { ConverterComponent } from "../components";
 /**
@@ -39,7 +39,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @param reflections  The reflections that should be grouped.
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
-    getReflectionGroups(reflections: DeclarationReflection[]): ReflectionGroup[];
+    getReflectionGroups(parent: ContainerReflection, reflections: DeclarationReflection[]): ReflectionGroup[];
     /**
      * Callback used to sort groups by name.
      */

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

@@ -135,7 +135,7 @@ let GroupPlugin = (() => {
                     !reflection.children.some((c) => c.kindOf(index_1.ReflectionKind.Module))) {
                     this.sortFunction(reflection.children);
                 }
-                reflection.groups = this.getReflectionGroups(reflection.children);
+                reflection.groups = this.getReflectionGroups(reflection, reflection.children);
             }
         }
         /**
@@ -188,7 +188,7 @@ let GroupPlugin = (() => {
          * @param reflections  The reflections that should be grouped.
          * @returns An array containing all children of the given reflection grouped by their kind.
          */
-        getReflectionGroups(reflections) {
+        getReflectionGroups(parent, reflections) {
             const groups = new Map();
             reflections.forEach((child) => {
                 for (const name of this.getGroups(child)) {
@@ -200,6 +200,22 @@ let GroupPlugin = (() => {
                     group.children.push(child);
                 }
             });
+            if (parent.comment) {
+                (0, utils_1.removeIf)(parent.comment.blockTags, (tag) => {
+                    if (tag.tag === "@groupDescription") {
+                        const { header, body } = models_1.Comment.splitPartsToHeaderAndBody(tag.content);
+                        const cat = groups.get(header);
+                        if (cat) {
+                            cat.description = body;
+                        }
+                        else {
+                            this.application.logger.warn(`Comment for ${parent.getFriendlyFullName()} includes @groupDescription for "${header}", but no child is placed in that group.`);
+                        }
+                        return true;
+                    }
+                    return false;
+                });
+            }
             return Array.from(groups.values()).sort(GroupPlugin.sortGroupCallback);
         }
         /**

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

@@ -10,4 +10,5 @@ export declare class LinkResolverPlugin extends ConverterComponent {
     initialize(): void;
     onResolve(context: Context): void;
     resolveLinks(project: ProjectReflection): void;
+    private resolveCategoryLinks;
 }

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

@@ -94,6 +94,25 @@ let LinkResolverPlugin = (() => {
                     reflection.readme) {
                     reflection.readme = this.owner.resolveLinks(reflection.readme, reflection);
                 }
+                if (reflection instanceof models_1.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);
@@ -112,6 +131,11 @@ let LinkResolverPlugin = (() => {
                 }
             }
         }
+        resolveCategoryLinks(category, owner) {
+            if (category.description) {
+                category.description = this.owner.resolveLinks(category.description, owner);
+            }
+        }
     };
     _LinkResolverPlugin_validation_accessor_storage = new WeakMap();
     __setFunctionName(_classThis, "LinkResolverPlugin");

package/dist/lib/converter/symbols.js

@@ -47,8 +47,8 @@ const conversionOrder = [
     typescript_1.default.SymbolFlags.BlockScopedVariable,
     typescript_1.default.SymbolFlags.FunctionScopedVariable,
     typescript_1.default.SymbolFlags.ExportValue,
-    typescript_1.default.SymbolFlags.TypeAlias,
     typescript_1.default.SymbolFlags.Function, // Before NamespaceModule
+    typescript_1.default.SymbolFlags.TypeAlias,
     typescript_1.default.SymbolFlags.Method,
     typescript_1.default.SymbolFlags.Interface,
     typescript_1.default.SymbolFlags.Property,
@@ -244,6 +244,12 @@ function convertFunctionOrMethod(context, symbol, exportSymbol) {
     // This will *NOT* be called for variables that look like functions, they need a special case.
     const isMethod = !!(symbol.flags &
         (typescript_1.default.SymbolFlags.Property | typescript_1.default.SymbolFlags.Method));
+    if (!isMethod) {
+        const comment = context.getComment(symbol, models_1.ReflectionKind.Function);
+        if (comment?.hasModifier("@class")) {
+            return convertSymbolAsClass(context, symbol, exportSymbol);
+        }
+    }
     const declarations = symbol.getDeclarations()?.filter(typescript_1.default.isFunctionLike) ?? [];
     // Don't do anything if we inherited this method and it is private.
     if (isMethod &&
@@ -483,7 +489,11 @@ function convertVariable(context, symbol, exportSymbol) {
     if (comment?.hasModifier("@namespace")) {
         return convertVariableAsNamespace(context, symbol, exportSymbol);
     }
-    if (type.getCallSignatures().length) {
+    if (comment?.hasModifier("@class")) {
+        return convertSymbolAsClass(context, symbol, exportSymbol);
+    }
+    if (type.getCallSignatures().length &&
+        !type.getConstructSignatures().length) {
         return convertVariableAsFunction(context, symbol, exportSymbol);
     }
     const reflection = context.createDeclarationReflection(context.scope.kindOf(models_1.ReflectionKind.VariableContainer)
@@ -556,8 +566,8 @@ function convertVariableAsFunction(context, symbol, exportSymbol) {
     for (const signature of type.getCallSignatures()) {
         (0, signature_1.createSignature)(reflectionContext, models_1.ReflectionKind.CallSignature, signature, symbol);
     }
-    convertFunctionProperties(context.withScope(reflection), symbol, type);
-    return typescript_1.default.SymbolFlags.Property | typescript_1.default.SymbolFlags.NamespaceModule;
+    return (convertFunctionProperties(context.withScope(reflection), symbol, type) |
+        typescript_1.default.SymbolFlags.Property);
 }
 function convertFunctionProperties(context, symbol, type) {
     // #2436/#2461: Functions created with Object.assign on a function likely have properties
@@ -574,6 +584,49 @@ function convertFunctionProperties(context, symbol, type) {
         convertSymbols(context, type.getProperties());
         return typescript_1.default.SymbolFlags.NamespaceModule;
     }
+    return typescript_1.default.SymbolFlags.None;
+}
+function convertSymbolAsClass(context, symbol, exportSymbol) {
+    const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Class, symbol, exportSymbol);
+    const rc = context.withScope(reflection);
+    context.finalizeDeclarationReflection(reflection);
+    if (!symbol.valueDeclaration) {
+        context.logger.error(`No value declaration found when converting ${symbol.name} as a class`, symbol.declarations?.[0]);
+        return;
+    }
+    const type = context.checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration);
+    rc.shouldBeStatic = true;
+    convertSymbols(rc, 
+    // Prototype is implicitly this class, don't document it.
+    type.getProperties().filter((prop) => prop.name !== "prototype"));
+    for (const sig of type.getCallSignatures()) {
+        (0, signature_1.createSignature)(rc, models_1.ReflectionKind.CallSignature, sig, undefined);
+    }
+    rc.shouldBeStatic = false;
+    const ctors = type.getConstructSignatures();
+    if (ctors.length) {
+        const constructMember = rc.createDeclarationReflection(models_1.ReflectionKind.Constructor, ctors?.[0]?.declaration?.symbol, void 0, "constructor");
+        // Modifiers are the same for all constructors
+        if (ctors.length && ctors[0].declaration) {
+            setModifiers(symbol, ctors[0].declaration, constructMember);
+        }
+        context.finalizeDeclarationReflection(constructMember);
+        const constructContext = rc.withScope(constructMember);
+        for (const sig of ctors) {
+            (0, signature_1.createConstructSignatureWithType)(constructContext, sig, reflection);
+        }
+        const instType = ctors[0].getReturnType();
+        convertSymbols(rc, instType.getProperties());
+        for (const sig of instType.getCallSignatures()) {
+            (0, signature_1.createSignature)(rc, models_1.ReflectionKind.CallSignature, sig, undefined);
+        }
+    }
+    else {
+        context.logger.warn(`${reflection.getFriendlyFullName()} is being converted as a class, but does not have any construct signatures`, symbol.valueDeclaration);
+    }
+    return (typescript_1.default.SymbolFlags.TypeAlias |
+        typescript_1.default.SymbolFlags.Interface |
+        typescript_1.default.SymbolFlags.Namespace);
 }
 function convertAccessor(context, symbol, exportSymbol) {
     const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Accessor, symbol, exportSymbol);

package/dist/lib/converter/types.js

@@ -71,15 +71,22 @@ function maybeConvertType(context, typeOrNode) {
     }
     return convertType(context, typeOrNode);
 }
+let typeConversionDepth = 0;
 function convertType(context, typeOrNode) {
     if (!typeOrNode) {
         return new models_1.IntrinsicType("any");
     }
+    if (typeConversionDepth > context.converter.maxTypeConversionDepth) {
+        return new models_1.UnknownType("...");
+    }
     loadConverters();
     if ("kind" in typeOrNode) {
         const converter = converters.get(typeOrNode.kind);
         if (converter) {
-            return converter.convert(context, typeOrNode);
+            ++typeConversionDepth;
+            const result = converter.convert(context, typeOrNode);
+            --typeConversionDepth;
+            return result;
         }
         return requestBugReport(context, typeOrNode);
     }
@@ -88,6 +95,7 @@ function convertType(context, typeOrNode) {
     // will use the origin when serializing
     // aliasSymbol check is important - #2468
     if (typeOrNode.isUnion() && typeOrNode.origin && !typeOrNode.aliasSymbol) {
+        // Don't increment typeConversionDepth as this is a transparent step to the user.
         return convertType(context, typeOrNode.origin);
     }
     // IgnoreErrors is important, without it, we can't assert that we will get a node.
@@ -106,7 +114,9 @@ function convertType(context, typeOrNode) {
             converter = typeLiteralConverter;
         }
         seenTypes.add(typeOrNode.id);
+        ++typeConversionDepth;
         const result = converter.convertType(context, typeOrNode, node);
+        --typeConversionDepth;
         seenTypes.delete(typeOrNode.id);
         return result;
     }
@@ -643,7 +653,9 @@ const unionConverter = {
         return new models_1.UnionType(node.types.map((type) => convertType(context, type)));
     },
     convertType(context, type) {
-        return new models_1.UnionType(type.types.map((type) => convertType(context, type)));
+        const types = type.types.map((type) => convertType(context, type));
+        sortLiteralUnion(types);
+        return new models_1.UnionType(types);
     },
 };
 const jsDocNullableTypeConverter = {
@@ -695,3 +707,13 @@ function kindToModifier(kind) {
             return undefined;
     }
 }
+function sortLiteralUnion(types) {
+    if (types.some((t) => t.type !== "literal" || typeof t.value !== "number")) {
+        return;
+    }
+    types.sort((a, b) => {
+        const aLit = a;
+        const bLit = b;
+        return aLit.value - bLit.value;
+    });
+}

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

@@ -1,4 +1,4 @@
-import type { DeclarationReflection } from ".";
+import type { CommentDisplayPart, DeclarationReflection } from ".";
 import type { Serializer, JSONOutput, Deserializer } from "../serialization";
 /**
  * A category of reflections.
@@ -12,6 +12,10 @@ export declare class ReflectionCategory {
      * The title, a string representation of this category.
      */
     title: string;
+    /**
+     * The user specified description, if any, set with `@categoryDescription`
+     */
+    description?: CommentDisplayPart[];
     /**
      * All reflections of this category.
      */
@@ -26,6 +30,6 @@ export declare class ReflectionCategory {
      * Do all children of this category have a separate document?
      */
     allChildrenHaveOwnDocument(): boolean;
-    toObject(_serializer: Serializer): JSONOutput.ReflectionCategory;
+    toObject(serializer: Serializer): JSONOutput.ReflectionCategory;
     fromObject(de: Deserializer, obj: JSONOutput.ReflectionCategory): void;
 }

package/dist/lib/models/ReflectionCategory.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReflectionCategory = void 0;
+const comments_1 = require("./comments");
 /**
  * A category of reflections.
  *
@@ -27,15 +28,21 @@ class ReflectionCategory {
     allChildrenHaveOwnDocument() {
         return this.children.every((child) => child.hasOwnDocument);
     }
-    toObject(_serializer) {
+    toObject(serializer) {
         return {
             title: this.title,
+            description: this.description
+                ? comments_1.Comment.serializeDisplayParts(serializer, this.description)
+                : undefined,
             children: this.children.length > 0
                 ? this.children.map((child) => child.id)
                 : undefined,
         };
     }
     fromObject(de, obj) {
+        if (obj.description) {
+            this.description = comments_1.Comment.deserializeDisplayParts(de, obj.description);
+        }
         if (obj.children) {
             de.defer((project) => {
                 for (const childId of obj.children || []) {