@depup/typedoc 0.28.17-depup.0

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

@@ -0,0 +1,48 @@
+import { ContainerReflection, type DeclarationReflection, type DocumentReflection } from "../../models/index.js";
+import { ConverterComponent } from "../components.js";
+import type { Converter } from "../converter.js";
+/**
+ * A handler that sorts and categorizes the found reflections in the resolving phase.
+ *
+ * The handler sets the ´category´ property of all reflections.
+ */
+export declare class CategoryPlugin extends ConverterComponent {
+    defaultSortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
+    accessor defaultCategory: string;
+    accessor categoryOrder: string[];
+    accessor categorizeByGroup: boolean;
+    static defaultCategory: string;
+    static WEIGHTS: string[];
+    constructor(owner: Converter);
+    private onRevive;
+    /**
+     * Triggered when the converter begins converting a project.
+     */
+    private setup;
+    /**
+     * Triggered when the converter has finished resolving a project.
+     *
+     * @param context  The context object describing the current state the converter is in.
+     */
+    private onEndResolve;
+    private categorize;
+    private groupCategorize;
+    private lumpCategorize;
+    /**
+     * Create a categorized representation of the given list of reflections.
+     *
+     * @param reflections  The reflections that should be categorized.
+     * @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.
+     *
+     * @param a The left reflection to sort.
+     * @param b The right reflection to sort.
+     * @returns The sorting weight.
+     */
+    private static sortCatCallback;
+    static getCategories(reflection: DeclarationReflection | DocumentReflection): Set<string>;
+}

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

@@ -0,0 +1,278 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import assert from "assert";
+import { ApplicationEvents } from "../../application-events.js";
+import { Comment, ContainerReflection, ReflectionCategory, ReflectionKind, } from "../../models/index.js";
+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.
+ *
+ * The handler sets the ´category´ property of all reflections.
+ */
+let CategoryPlugin = (() => {
+    let _classSuper = ConverterComponent;
+    let _defaultCategory_decorators;
+    let _defaultCategory_initializers = [];
+    let _defaultCategory_extraInitializers = [];
+    let _categoryOrder_decorators;
+    let _categoryOrder_initializers = [];
+    let _categoryOrder_extraInitializers = [];
+    let _categorizeByGroup_decorators;
+    let _categorizeByGroup_initializers = [];
+    let _categorizeByGroup_extraInitializers = [];
+    return class CategoryPlugin extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _defaultCategory_decorators = [Option("defaultCategory")];
+            _categoryOrder_decorators = [Option("categoryOrder")];
+            _categorizeByGroup_decorators = [Option("categorizeByGroup")];
+            __esDecorate(this, null, _defaultCategory_decorators, { kind: "accessor", name: "defaultCategory", static: false, private: false, access: { has: obj => "defaultCategory" in obj, get: obj => obj.defaultCategory, set: (obj, value) => { obj.defaultCategory = value; } }, metadata: _metadata }, _defaultCategory_initializers, _defaultCategory_extraInitializers);
+            __esDecorate(this, null, _categoryOrder_decorators, { kind: "accessor", name: "categoryOrder", static: false, private: false, access: { has: obj => "categoryOrder" in obj, get: obj => obj.categoryOrder, set: (obj, value) => { obj.categoryOrder = value; } }, metadata: _metadata }, _categoryOrder_initializers, _categoryOrder_extraInitializers);
+            __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 });
+        }
+        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; }
+        #categoryOrder_accessor_storage = (__runInitializers(this, _defaultCategory_extraInitializers), __runInitializers(this, _categoryOrder_initializers, void 0));
+        get categoryOrder() { return this.#categoryOrder_accessor_storage; }
+        set categoryOrder(value) { this.#categoryOrder_accessor_storage = value; }
+        #categorizeByGroup_accessor_storage = (__runInitializers(this, _categoryOrder_extraInitializers), __runInitializers(this, _categorizeByGroup_initializers, void 0));
+        get categorizeByGroup() { return this.#categorizeByGroup_accessor_storage; }
+        set categorizeByGroup(value) { this.#categorizeByGroup_accessor_storage = value; }
+        // For use in static methods
+        static defaultCategory = "Other";
+        static WEIGHTS = [];
+        constructor(owner) {
+            super(owner);
+            __runInitializers(this, _categorizeByGroup_extraInitializers);
+            this.owner.on(ConverterEvents.RESOLVE_END, this.onEndResolve.bind(this), -200);
+            this.application.on(ApplicationEvents.REVIVE, this.onRevive.bind(this), -200);
+        }
+        onRevive(project) {
+            this.setup();
+            this.categorize(project);
+            for (const refl of project.getReflectionsByKind(ReflectionKind.SomeModule)) {
+                assert(refl.isDeclaration());
+                this.categorize(refl);
+            }
+        }
+        /**
+         * Triggered when the converter begins converting a project.
+         */
+        setup() {
+            this.defaultSortFunction = getSortFunction(this.application.options);
+            // Set up static properties
+            if (this.defaultCategory) {
+                CategoryPlugin.defaultCategory = this.defaultCategory;
+            }
+            CategoryPlugin.WEIGHTS = this.categoryOrder;
+        }
+        /**
+         * Triggered when the converter has finished resolving a project.
+         *
+         * @param context  The context object describing the current state the converter is in.
+         */
+        onEndResolve(context) {
+            this.setup();
+            const project = context.project;
+            this.categorize(project);
+            for (const id in project.reflections) {
+                const reflection = project.reflections[id];
+                if (reflection instanceof ContainerReflection) {
+                    this.categorize(reflection);
+                }
+            }
+        }
+        categorize(obj) {
+            if (this.categorizeByGroup && obj.groups) {
+                this.groupCategorize(obj);
+            }
+            else {
+                this.lumpCategorize(obj);
+            }
+        }
+        groupCategorize(obj) {
+            if (!obj.groups || obj.groups.length === 0) {
+                return;
+            }
+            obj.groups.forEach((group) => {
+                if (group.categories)
+                    return;
+                group.categories = this.getReflectionCategories(obj, group.children);
+                if (group.categories.length > 1) {
+                    group.categories.sort(CategoryPlugin.sortCatCallback);
+                }
+                else if (group.categories.length === 1 &&
+                    group.categories[0].title === CategoryPlugin.defaultCategory) {
+                    // no categories if everything is uncategorized
+                    group.categories = undefined;
+                }
+            });
+        }
+        lumpCategorize(obj) {
+            if (!obj.childrenIncludingDocuments || obj.categories) {
+                return;
+            }
+            obj.categories = this.getReflectionCategories(obj, obj.childrenIncludingDocuments);
+            if (obj.categories.length > 1) {
+                obj.categories.sort(CategoryPlugin.sortCatCallback);
+            }
+            else if (obj.categories.length === 1 &&
+                obj.categories[0].title === CategoryPlugin.defaultCategory) {
+                // no categories if everything is uncategorized
+                obj.categories = undefined;
+            }
+        }
+        /**
+         * Create a categorized representation of the given list of reflections.
+         *
+         * @param reflections  The reflections that should be categorized.
+         * @returns An array containing all children of the given reflection categorized
+         */
+        getReflectionCategories(parent, reflections) {
+            const categories = new Map();
+            for (const child of reflections) {
+                const childCategories = CategoryPlugin.getCategories(child);
+                if (childCategories.size === 0) {
+                    childCategories.add(CategoryPlugin.defaultCategory);
+                }
+                for (const childCat of childCategories) {
+                    const category = categories.get(childCat);
+                    if (category) {
+                        category.children.push(child);
+                    }
+                    else {
+                        const cat = new ReflectionCategory(childCat);
+                        cat.children.push(child);
+                        categories.set(childCat, cat);
+                    }
+                }
+            }
+            if (parent.comment) {
+                for (const tag of parent.comment.blockTags) {
+                    if (tag.tag === "@categoryDescription") {
+                        const { header, body } = Comment.splitPartsToHeaderAndBody(tag.content);
+                        const cat = categories.get(header);
+                        if (cat) {
+                            cat.description = body;
+                        }
+                        else {
+                            this.application.logger.warn(i18n
+                                .comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group(parent.getFriendlyFullName(), header));
+                        }
+                    }
+                }
+            }
+            for (const cat of categories.values()) {
+                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.
+         *
+         * @param a The left reflection to sort.
+         * @param b The right reflection to sort.
+         * @returns The sorting weight.
+         */
+        static sortCatCallback(a, b) {
+            let aWeight = CategoryPlugin.WEIGHTS.indexOf(a.title);
+            let bWeight = CategoryPlugin.WEIGHTS.indexOf(b.title);
+            if (aWeight === -1 || bWeight === -1) {
+                let asteriskIndex = CategoryPlugin.WEIGHTS.indexOf("*");
+                if (asteriskIndex === -1) {
+                    asteriskIndex = CategoryPlugin.WEIGHTS.length;
+                }
+                if (aWeight === -1) {
+                    aWeight = asteriskIndex;
+                }
+                if (bWeight === -1) {
+                    bWeight = asteriskIndex;
+                }
+            }
+            if (aWeight === bWeight) {
+                return a.title > b.title ? 1 : -1;
+            }
+            return aWeight - bWeight;
+        }
+        static getCategories(reflection) {
+            const categories = new Set();
+            function discoverCategories(comment) {
+                if (!comment)
+                    return;
+                for (const tag of comment.blockTags) {
+                    if (tag.tag === "@category") {
+                        categories.add(Comment.combineDisplayParts(tag.content).trim());
+                    }
+                }
+            }
+            discoverCategories(reflection.comment);
+            if (reflection.isDeclaration()) {
+                for (const sig of reflection.getNonIndexSignatures()) {
+                    discoverCategories(sig.comment);
+                }
+                if (reflection.type?.type === "reflection") {
+                    discoverCategories(reflection.type.declaration.comment);
+                    for (const sig of reflection.type.declaration.getNonIndexSignatures()) {
+                        discoverCategories(sig.comment);
+                    }
+                }
+            }
+            if (reflection.isDocument() && "category" in reflection.frontmatter) {
+                categories.add(String(reflection.frontmatter["category"]));
+            }
+            categories.delete("");
+            return categories;
+        }
+    };
+})();
+export { CategoryPlugin };

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

@@ -0,0 +1,128 @@
+import { type TagString } from "#utils";
+import { ConverterComponent } from "../components.js";
+import type { Converter } from "../converter.js";
+/**
+ * Handles most behavior triggered by comments. `@group` and `@category` are handled by their respective plugins, but everything else is here.
+ *
+ * How it works today
+ * ==================
+ * During conversion:
+ * - Handle visibility flags (`@private`, `@protected`. `@public`)
+ * - Handle module renames (`@module`)
+ * - Remove excluded tags & comment discovery tags (`@module`, `@packageDocumentation`)
+ * - Copy comments for type parameters from the parent container (for classes/interfaces)
+ *
+ * Resolve begin:
+ * - Remove hidden reflections
+ *
+ * Resolve:
+ * - Apply `@label` tag
+ * - Copy comments on signature containers to the signature if signatures don't already have a comment
+ *   and then remove the comment on the container.
+ * - Copy comments to parameters and type parameters (for signatures)
+ * - Apply `@group` and `@category` tags
+ *
+ * Resolve end:
+ * - Copy auto inherited comments from heritage clauses
+ * - Handle `@inheritDoc`
+ * - Resolve `@link` tags to point to target reflections
+ *
+ * How it should work
+ * ==================
+ * During conversion:
+ * - Handle visibility flags (`@private`, `@protected`. `@public`)
+ * - Handle module renames (`@module`)
+ * - Remove excluded tags & comment discovery tags (`@module`, `@packageDocumentation`)
+ *
+ * Resolve begin (100):
+ * - Copy auto inherited comments from heritage clauses
+ * - Apply `@label` tag
+ *
+ * Resolve begin (75)
+ * - Handle `@inheritDoc`
+ *
+ * Resolve begin (50)
+ * - Copy comments on signature containers to the signature if signatures don't already have a comment
+ *   and then remove the comment on the container.
+ * - Copy comments for type parameters from the parent container (for classes/interfaces)
+ *
+ * Resolve begin (25)
+ * - Remove hidden reflections
+ *
+ * Resolve:
+ * - Copy comments to parameters and type parameters (for signatures)
+ * - Apply `@group` and `@category` tags
+ *
+ * Resolve end:
+ * - Resolve `@link` tags to point to target reflections
+ */
+export declare class CommentPlugin extends ConverterComponent {
+    accessor excludeTags: TagString[];
+    accessor cascadedModifierTags: TagString[];
+    accessor excludeInternal: boolean;
+    accessor excludePrivate: boolean;
+    accessor excludePrivateClassFields: boolean;
+    accessor excludeProtected: boolean;
+    accessor excludeNotDocumented: boolean;
+    accessor excludeCategories: string[];
+    accessor defaultCategory: string;
+    accessor suppressCommentWarningsInDeclarationFiles: boolean;
+    private _excludeKinds;
+    private get excludeNotDocumentedKinds();
+    constructor(owner: Converter);
+    /**
+     * Apply all comment tag modifiers to the given reflection.
+     *
+     * @param reflection  The reflection the modifiers should be applied to.
+     * @param comment  The comment that should be searched for modifiers.
+     */
+    private applyModifiers;
+    /**
+     * Triggered when the converter has created a type parameter reflection.
+     *
+     * @param context  The context object describing the current state the converter is in.
+     * @param reflection  The reflection that is currently processed.
+     */
+    private onCreateTypeParameter;
+    /**
+     * Triggered when the converter has created a declaration or signature reflection.
+     *
+     * Invokes the comment parser.
+     *
+     * @param context  The context object describing the current state the converter is in.
+     * @param reflection  The reflection that is currently processed.
+     * @param node  The node that is currently processed if available.
+     */
+    private onDeclaration;
+    /**
+     * Triggered when the converter begins resolving a project.
+     *
+     * @param context  The context object describing the current state the converter is in.
+     */
+    private onBeginResolve;
+    /**
+     * Triggered when the converter resolves a reflection.
+     *
+     * Cleans up comment tags related to signatures like `@param` or `@returns`
+     * and moves their data to the corresponding parameter reflections.
+     *
+     * This hook also copies over the comment of function implementations to their
+     * signatures.
+     *
+     * @param context  The context object describing the current state the converter is in.
+     * @param reflection  The reflection that is currently resolved.
+     */
+    private onResolve;
+    private moveSignatureParamComments;
+    private removeExcludedTags;
+    private cascadeModifiers;
+    /**
+     * Determines whether or not a reflection has been hidden
+     *
+     * @param reflection Reflection to check if hidden
+     */
+    private isHidden;
+    private excludedByCategory;
+    private validateParamTags;
+    private suppressCommentWarnings;
+}