typedoc 0.25.13 → 0.26.0-beta.0

package/dist/lib/models/comments/comment.js

@@ -1,9 +1,44 @@
 "use strict";
+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;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Comment = exports.CommentTag = void 0;
 const utils_1 = require("../../utils");
 const kind_1 = require("../reflections/kind");
 const ReflectionSymbolId_1 = require("../reflections/ReflectionSymbolId");
+const general_1 = require("../../utils/general");
 /**
  * A model that represents a single TypeDoc comment tag.
  *
@@ -46,321 +81,365 @@ exports.CommentTag = CommentTag;
  * through the {@link DeclarationReflection.comment} property.
  * @category Comments
  */
-class Comment {
-    /**
-     * Debugging utility for combining parts into a simple string. Not suitable for
-     * rendering, but can be useful in tests.
-     */
-    static combineDisplayParts(parts) {
-        let result = "";
-        for (const item of parts || []) {
-            switch (item.kind) {
-                case "text":
-                case "code":
-                    result += item.text;
-                    break;
-                case "inline-tag":
-                    result += `{${item.tag} ${item.text}}`;
-                    break;
-                default:
-                    (0, utils_1.assertNever)(item);
+let Comment = (() => {
+    var _a;
+    let _sourcePath_decorators;
+    let _sourcePath_initializers = [];
+    let _sourcePath_extraInitializers = [];
+    let _discoveryId_decorators;
+    let _discoveryId_initializers = [];
+    let _discoveryId_extraInitializers = [];
+    return _a = class Comment {
+            /**
+             * Debugging utility for combining parts into a simple string. Not suitable for
+             * rendering, but can be useful in tests.
+             */
+            static combineDisplayParts(parts) {
+                let result = "";
+                for (const item of parts || []) {
+                    switch (item.kind) {
+                        case "text":
+                        case "code":
+                            result += item.text;
+                            break;
+                        case "inline-tag":
+                            result += `{${item.tag} ${item.text}}`;
+                            break;
+                        default:
+                            (0, utils_1.assertNever)(item);
+                    }
+                }
+                return result;
             }
-        }
-        return result;
-    }
-    /**
-     * Helper function to convert an array of comment display parts into markdown suitable for
-     * passing into Marked. `urlTo` will be used to resolve urls to any reflections linked to with
-     * `@link` tags.
-     */
-    static displayPartsToMarkdown(parts, urlTo) {
-        const result = [];
-        for (const part of parts) {
-            switch (part.kind) {
-                case "text":
-                case "code":
-                    result.push(part.text);
-                    break;
-                case "inline-tag":
-                    switch (part.tag) {
-                        case "@label":
-                        case "@inheritdoc": // Shouldn't happen
-                            break; // Not rendered.
-                        case "@link":
-                        case "@linkcode":
-                        case "@linkplain": {
-                            if (part.target) {
-                                let url;
-                                let kindClass;
-                                if (typeof part.target === "string") {
-                                    url = part.target;
-                                }
-                                else if (part.target && "id" in part.target) {
-                                    // No point in trying to resolve a ReflectionSymbolId at this point, we've already
-                                    // tried and failed during the resolution step.
-                                    url = urlTo(part.target);
-                                    kindClass = kind_1.ReflectionKind.classString(part.target.kind);
+            /**
+             * Helper function to convert an array of comment display parts into markdown suitable for
+             * passing into markdown-it.
+             * @param urlTo - Used to resolve urls to any reflections linked to with `@link` tags..
+             * @param useHtml - If set, will produce `<a>` links which can be colored according to the reflection type they are pointed at.
+             */
+            static displayPartsToMarkdown(parts, urlTo, useHtml) {
+                const result = [];
+                for (const part of parts) {
+                    switch (part.kind) {
+                        case "text":
+                        case "code":
+                            result.push(part.text);
+                            break;
+                        case "inline-tag":
+                            switch (part.tag) {
+                                case "@label":
+                                case "@inheritdoc": // Shouldn't happen
+                                    break; // Not rendered.
+                                case "@link":
+                                case "@linkcode":
+                                case "@linkplain": {
+                                    if (part.target) {
+                                        let url;
+                                        let kindClass;
+                                        if (typeof part.target === "string") {
+                                            url = part.target;
+                                        }
+                                        else if (part.target && "id" in part.target) {
+                                            // No point in trying to resolve a ReflectionSymbolId at this point, we've already
+                                            // tried and failed during the resolution step.
+                                            url = urlTo(part.target);
+                                            kindClass = kind_1.ReflectionKind.classString(part.target.kind);
+                                        }
+                                        if (useHtml) {
+                                            const text = part.tag === "@linkcode"
+                                                ? `<code>${part.text}</code>`
+                                                : part.text;
+                                            result.push(url
+                                                ? `<a href="${url}"${kindClass
+                                                    ? ` class="${kindClass}"`
+                                                    : ""}>${text}</a>`
+                                                : part.text);
+                                        }
+                                        else {
+                                            const text = part.tag === "@linkcode"
+                                                ? "`" + part.text + "`"
+                                                : part.text;
+                                            result.push(url ? `[${text}](${url})` : text);
+                                        }
+                                    }
+                                    else {
+                                        result.push(part.text);
+                                    }
+                                    break;
                                 }
-                                const text = part.tag === "@linkcode"
-                                    ? `<code>${part.text}</code>`
-                                    : part.text;
-                                result.push(url
-                                    ? `<a href="${url}"${kindClass
-                                        ? ` class="${kindClass}"`
-                                        : ""}>${text}</a>`
-                                    : part.text);
-                            }
-                            else {
-                                result.push(part.text);
+                                default:
+                                    // Hmm... probably want to be able to render these somehow, so custom inline tags can be given
+                                    // special rendering rules. Future capability. For now, just render their text.
+                                    result.push(`{${part.tag} ${part.text}}`);
+                                    break;
                             }
                             break;
-                        }
                         default:
-                            // Hmm... probably want to be able to render these somehow, so custom inline tags can be given
-                            // special rendering rules. Future capability. For now, just render their text.
-                            result.push(`{${part.tag} ${part.text}}`);
-                            break;
+                            (0, utils_1.assertNever)(part);
                     }
-                    break;
-                default:
-                    (0, utils_1.assertNever)(part);
+                }
+                return result.join("");
             }
-        }
-        return result.join("");
-    }
-    /**
-     * Helper utility to clone {@link Comment.summary} or {@link CommentTag.content}
-     */
-    static cloneDisplayParts(parts) {
-        return parts.map((p) => ({ ...p }));
-    }
-    static serializeDisplayParts(serializer, parts) {
-        return parts?.map((part) => {
-            switch (part.kind) {
-                case "text":
-                case "code":
-                    return { ...part };
-                case "inline-tag": {
-                    let target;
-                    if (typeof part.target === "string") {
-                        target = part.target;
+            /**
+             * Helper utility to clone {@link Comment.summary} or {@link CommentTag.content}
+             */
+            static cloneDisplayParts(parts) {
+                return parts.map((p) => ({ ...p }));
+            }
+            static serializeDisplayParts(serializer, parts) {
+                return parts?.map((part) => {
+                    switch (part.kind) {
+                        case "text":
+                        case "code":
+                            return { ...part };
+                        case "inline-tag": {
+                            let target;
+                            if (typeof part.target === "string") {
+                                target = part.target;
+                            }
+                            else if (part.target) {
+                                if ("id" in part.target) {
+                                    target = part.target.id;
+                                }
+                                else {
+                                    target = part.target.toObject(serializer);
+                                }
+                            }
+                            return {
+                                ...part,
+                                target,
+                            };
+                        }
                     }
-                    else if (part.target) {
-                        if ("id" in part.target) {
-                            target = part.target.id;
+                });
+            }
+            //Since display parts are plain objects, this lives here
+            static deserializeDisplayParts(de, parts) {
+                const links = [];
+                const result = parts.map((part) => {
+                    switch (part.kind) {
+                        case "text":
+                        case "code":
+                            return { ...part };
+                        case "inline-tag": {
+                            if (typeof part.target === "number") {
+                                const part2 = {
+                                    kind: part.kind,
+                                    tag: part.tag,
+                                    text: part.text,
+                                    target: undefined,
+                                    tsLinkText: part.tsLinkText,
+                                };
+                                links.push([part.target, part2]);
+                                return part2;
+                            }
+                            else if (typeof part.target === "string" ||
+                                part.target === undefined) {
+                                return {
+                                    kind: "inline-tag",
+                                    tag: part.tag,
+                                    text: part.text,
+                                    target: part.target,
+                                    tsLinkText: part.tsLinkText,
+                                };
+                            }
+                            else if (typeof part.target === "object") {
+                                return {
+                                    kind: "inline-tag",
+                                    tag: part.tag,
+                                    text: part.text,
+                                    target: new ReflectionSymbolId_1.ReflectionSymbolId(part.target),
+                                    tsLinkText: part.tsLinkText,
+                                };
+                            }
+                            else {
+                                (0, utils_1.assertNever)(part.target);
+                            }
                         }
-                        else {
-                            target = part.target.toObject(serializer);
+                    }
+                });
+                if (links.length) {
+                    de.defer((project) => {
+                        for (const [oldId, part] of links) {
+                            part.target = project.getReflectionById(de.oldIdToNewId[oldId] ?? -1);
+                            if (!part.target) {
+                                de.logger.warn(de.application.i18n.serialized_project_referenced_0_not_part_of_project(oldId.toString()));
+                            }
                         }
+                    });
+                }
+                return result;
+            }
+            /**
+             * Splits the provided parts into a header (first line, as a string)
+             * and body (remaining lines). If the header line contains inline tags
+             * they will be serialized to a string.
+             */
+            static splitPartsToHeaderAndBody(parts) {
+                let index = parts.findIndex((part) => {
+                    switch (part.kind) {
+                        case "text":
+                        case "code":
+                            return part.text.includes("\n");
+                        case "inline-tag":
+                            return false;
                     }
+                });
+                if (index === -1) {
                     return {
-                        ...part,
-                        target,
+                        header: _a.combineDisplayParts(parts),
+                        body: [],
                     };
                 }
-            }
-        });
-    }
-    //Since display parts are plain objects, this lives here
-    static deserializeDisplayParts(de, parts) {
-        const links = [];
-        const result = parts.map((part) => {
-            switch (part.kind) {
-                case "text":
-                case "code":
-                    return { ...part };
-                case "inline-tag": {
-                    if (typeof part.target === "number") {
-                        const part2 = {
-                            kind: part.kind,
-                            tag: part.tag,
-                            text: part.text,
-                            target: undefined,
-                            tsLinkText: part.tsLinkText,
-                        };
-                        links.push([part.target, part2]);
-                        return part2;
-                    }
-                    else if (typeof part.target === "string" ||
-                        part.target === undefined) {
-                        return {
-                            kind: "inline-tag",
-                            tag: part.tag,
-                            text: part.text,
-                            target: part.target,
-                            tsLinkText: part.tsLinkText,
-                        };
-                    }
-                    else if (typeof part.target === "object") {
-                        return {
-                            kind: "inline-tag",
-                            tag: part.tag,
-                            text: part.text,
-                            target: new ReflectionSymbolId_1.ReflectionSymbolId(part.target),
-                            tsLinkText: part.tsLinkText,
-                        };
-                    }
-                    else {
-                        (0, utils_1.assertNever)(part.target);
-                    }
+                // Do not split a code block, stop the header at the end of the previous block
+                if (parts[index].kind === "code") {
+                    --index;
                 }
-            }
-        });
-        if (links.length) {
-            de.defer((project) => {
-                for (const [oldId, part] of links) {
-                    part.target = project.getReflectionById(de.oldIdToNewId[oldId] ?? -1);
-                    if (!part.target) {
-                        de.logger.warn(`Serialized project contained a link to ${oldId} (${part.text}), which was not a part of the project.`);
-                    }
+                if (index === -1) {
+                    return { header: "", body: _a.cloneDisplayParts(parts) };
                 }
-            });
-        }
-        return result;
-    }
-    /**
-     * Splits the provided parts into a header (first line, as a string)
-     * and body (remaining lines). If the header line contains inline tags
-     * they will be serialized to a string.
-     */
-    static splitPartsToHeaderAndBody(parts) {
-        let index = parts.findIndex((part) => {
-            switch (part.kind) {
-                case "text":
-                case "code":
-                    return part.text.includes("\n");
-                case "inline-tag":
-                    return false;
+                let header = _a.combineDisplayParts(parts.slice(0, index));
+                const split = parts[index].text.indexOf("\n");
+                let body;
+                if (split === -1) {
+                    header += parts[index].text;
+                    body = _a.cloneDisplayParts(parts.slice(index + 1));
+                }
+                else {
+                    header += parts[index].text.substring(0, split);
+                    body = _a.cloneDisplayParts(parts.slice(index));
+                    body[0].text = body[0].text.substring(split + 1);
+                }
+                if (!body[0].text) {
+                    body.shift();
+                }
+                return { header: header.trim(), body };
             }
-        });
-        if (index === -1) {
-            return {
-                header: Comment.combineDisplayParts(parts),
-                body: [],
-            };
-        }
-        // Do not split a code block, stop the header at the end of the previous block
-        if (parts[index].kind === "code") {
-            --index;
-        }
-        if (index === -1) {
-            return { header: "", body: Comment.cloneDisplayParts(parts) };
-        }
-        let header = Comment.combineDisplayParts(parts.slice(0, index));
-        const split = parts[index].text.indexOf("\n");
-        let body;
-        if (split === -1) {
-            header += parts[index].text;
-            body = Comment.cloneDisplayParts(parts.slice(index + 1));
-        }
-        else {
-            header += parts[index].text.substring(0, split);
-            body = Comment.cloneDisplayParts(parts.slice(index));
-            body[0].text = body[0].text.substring(split + 1);
-        }
-        if (!body[0].text) {
-            body.shift();
-        }
-        return { header: header.trim(), body };
-    }
-    /**
-     * Creates a new Comment instance.
-     */
-    constructor(summary = [], blockTags = [], modifierTags = new Set()) {
-        /**
-         * All associated block level tags.
-         */
-        this.blockTags = [];
-        /**
-         * All modifier tags present on the comment, e.g. `@alpha`, `@beta`.
-         */
-        this.modifierTags = new Set();
-        this.summary = summary;
-        this.blockTags = blockTags;
-        this.modifierTags = modifierTags;
-        extractLabelTag(this);
-    }
-    /**
-     * Create a deep clone of this comment.
-     */
-    clone() {
-        return new Comment(Comment.cloneDisplayParts(this.summary), this.blockTags.map((tag) => tag.clone()), new Set(this.modifierTags));
-    }
-    /**
-     * Returns true if this comment is completely empty.
-     * @internal
-     */
-    isEmpty() {
-        return !this.hasVisibleComponent() && this.modifierTags.size === 0;
-    }
-    /**
-     * Has this comment a visible component?
-     *
-     * @returns TRUE when this comment has a visible component.
-     */
-    hasVisibleComponent() {
-        return (this.summary.some((x) => x.kind !== "text" || x.text !== "") ||
-            this.blockTags.length > 0);
-    }
-    /**
-     * Test whether this comment contains a tag with the given name.
-     *
-     * @param tagName  The name of the tag to look for.
-     * @returns TRUE when this comment contains a tag with the given name, otherwise FALSE.
-     */
-    hasModifier(tagName) {
-        return this.modifierTags.has(tagName);
-    }
-    removeModifier(tagName) {
-        this.modifierTags.delete(tagName);
-    }
-    /**
-     * Return the first tag with the given name.
-     *
-     * @param tagName  The name of the tag to look for.
-     * @returns The found tag or undefined.
-     */
-    getTag(tagName) {
-        return this.blockTags.find((tag) => tag.tag === tagName);
-    }
-    /**
-     * Get all tags with the given tag name.
-     */
-    getTags(tagName) {
-        return this.blockTags.filter((tag) => tag.tag === tagName);
-    }
-    getIdentifiedTag(identifier, tagName) {
-        return this.blockTags.find((tag) => tag.tag === tagName && tag.name === identifier);
-    }
-    /**
-     * Removes all block tags with the given tag name from the comment.
-     * @param tagName
-     */
-    removeTags(tagName) {
-        (0, utils_1.removeIf)(this.blockTags, (tag) => tag.tag === tagName);
-    }
-    toObject(serializer) {
-        return {
-            summary: Comment.serializeDisplayParts(serializer, this.summary),
-            blockTags: serializer.toObjectsOptional(this.blockTags),
-            modifierTags: this.modifierTags.size > 0
-                ? Array.from(this.modifierTags)
-                : undefined,
-            label: this.label,
-        };
-    }
-    fromObject(de, obj) {
-        this.summary = Comment.deserializeDisplayParts(de, obj.summary);
-        this.blockTags =
-            obj.blockTags?.map((tagObj) => {
-                const tag = new CommentTag(tagObj.tag, []);
-                de.fromObject(tag, tagObj);
-                return tag;
-            }) || [];
-        this.modifierTags = new Set(obj.modifierTags);
-        this.label = obj.label;
-    }
-}
+            /**
+             * Creates a new Comment instance.
+             */
+            constructor(summary = [], blockTags = [], modifierTags = new Set()) {
+                /**
+                 * All associated block level tags.
+                 */
+                this.blockTags = [];
+                /**
+                 * All modifier tags present on the comment, e.g. `@alpha`, `@beta`.
+                 */
+                this.modifierTags = new Set();
+                /**
+                 * Full path to the file where this comment originated from, if any.
+                 * This field will not be serialized, so will not be present when handling JSON-revived reflections.
+                 *
+                 * Note: This field is non-enumerable to make testing comment contents with `deepEqual` easier.
+                 */
+                this.sourcePath = __runInitializers(this, _sourcePath_initializers, void 0);
+                /**
+                 * Internal discovery ID used to prevent symbol comments from
+                 * being duplicated on signatures. Only set when the comment was created
+                 * @internal
+                 */
+                this.discoveryId = (__runInitializers(this, _sourcePath_extraInitializers), __runInitializers(this, _discoveryId_initializers, void 0));
+                __runInitializers(this, _discoveryId_extraInitializers);
+                this.summary = summary;
+                this.blockTags = blockTags;
+                this.modifierTags = modifierTags;
+                extractLabelTag(this);
+            }
+            /**
+             * Create a deep clone of this comment.
+             */
+            clone() {
+                const comment = new _a(_a.cloneDisplayParts(this.summary), this.blockTags.map((tag) => tag.clone()), new Set(this.modifierTags));
+                comment.discoveryId = this.discoveryId;
+                comment.sourcePath = this.sourcePath;
+                return comment;
+            }
+            /**
+             * Returns true if this comment is completely empty.
+             * @internal
+             */
+            isEmpty() {
+                return !this.hasVisibleComponent() && this.modifierTags.size === 0;
+            }
+            /**
+             * Has this comment a visible component?
+             *
+             * @returns TRUE when this comment has a visible component.
+             */
+            hasVisibleComponent() {
+                return (this.summary.some((x) => x.kind !== "text" || x.text !== "") ||
+                    this.blockTags.length > 0);
+            }
+            /**
+             * Test whether this comment contains a tag with the given name.
+             *
+             * @param tagName  The name of the tag to look for.
+             * @returns TRUE when this comment contains a tag with the given name, otherwise FALSE.
+             */
+            hasModifier(tagName) {
+                return this.modifierTags.has(tagName);
+            }
+            removeModifier(tagName) {
+                this.modifierTags.delete(tagName);
+            }
+            /**
+             * Return the first tag with the given name.
+             *
+             * @param tagName  The name of the tag to look for.
+             * @returns The found tag or undefined.
+             */
+            getTag(tagName) {
+                return this.blockTags.find((tag) => tag.tag === tagName);
+            }
+            /**
+             * Get all tags with the given tag name.
+             */
+            getTags(tagName) {
+                return this.blockTags.filter((tag) => tag.tag === tagName);
+            }
+            getIdentifiedTag(identifier, tagName) {
+                return this.blockTags.find((tag) => tag.tag === tagName && tag.name === identifier);
+            }
+            /**
+             * Removes all block tags with the given tag name from the comment.
+             * @param tagName
+             */
+            removeTags(tagName) {
+                (0, utils_1.removeIf)(this.blockTags, (tag) => tag.tag === tagName);
+            }
+            toObject(serializer) {
+                return {
+                    summary: _a.serializeDisplayParts(serializer, this.summary),
+                    blockTags: serializer.toObjectsOptional(this.blockTags),
+                    modifierTags: this.modifierTags.size > 0
+                        ? Array.from(this.modifierTags)
+                        : undefined,
+                    label: this.label,
+                };
+            }
+            fromObject(de, obj) {
+                this.summary = _a.deserializeDisplayParts(de, obj.summary);
+                this.blockTags =
+                    obj.blockTags?.map((tagObj) => {
+                        const tag = new CommentTag(tagObj.tag, []);
+                        de.fromObject(tag, tagObj);
+                        return tag;
+                    }) || [];
+                this.modifierTags = new Set(obj.modifierTags);
+                this.label = obj.label;
+            }
+        },
+        (() => {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _sourcePath_decorators = [general_1.NonEnumerable];
+            _discoveryId_decorators = [general_1.NonEnumerable];
+            __esDecorate(null, null, _sourcePath_decorators, { kind: "field", name: "sourcePath", static: false, private: false, access: { has: obj => "sourcePath" in obj, get: obj => obj.sourcePath, set: (obj, value) => { obj.sourcePath = value; } }, metadata: _metadata }, _sourcePath_initializers, _sourcePath_extraInitializers);
+            __esDecorate(null, null, _discoveryId_decorators, { kind: "field", name: "discoveryId", static: false, private: false, access: { has: obj => "discoveryId" in obj, get: obj => obj.discoveryId, set: (obj, value) => { obj.discoveryId = value; } }, metadata: _metadata }, _discoveryId_initializers, _discoveryId_extraInitializers);
+            if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        })(),
+        _a;
+})();
 exports.Comment = Comment;
 function extractLabelTag(comment) {
     const index = comment.summary.findIndex((part) => part.kind === "inline-tag" && part.tag === "@label");