typedoc 0.23.9 → 0.23.12

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { Converter, Context, type CommentParserConfig } from "./lib/converter";
 export { Renderer, DefaultTheme, DefaultThemeRenderContext, UrlMapping, Theme, PageEvent, RendererEvent, MarkdownEvent, IndexEvent, } from "./lib/output";
 export type { RenderTemplate, RendererHooks } from "./lib/output";
 export { ArgumentsReader, BindOption, CommentStyle, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, MinimalSourceFile, } from "./lib/utils";
-export type { OptionsReader, TypeDocOptions, TypeDocOptionMap, ValidationOptions, TypeDocOptionValues, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, ManuallyValidatedOption, } from "./lib/utils";
+export type { OptionsReader, TypeDocOptions, TypeDocOptionMap, ValidationOptions, TypeDocOptionValues, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, ObjectDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, ManuallyValidatedOption, } from "./lib/utils";
 export type { EventMap, EventCallback } from "./lib/utils/events";
 export { JSONOutput, Serializer, type SerializerComponent, SerializeEvent, } from "./lib/serialization";
 export type { SerializeEventData } from "./lib/serialization";

package/dist/lib/application-events.d.ts

@@ -0,0 +1,3 @@
+export declare const ApplicationEvents: {
+    BOOTSTRAP_END: string;
+};

package/dist/lib/application-events.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApplicationEvents = void 0;
+exports.ApplicationEvents = {
+    BOOTSTRAP_END: "bootstrapEnd",
+};

package/dist/lib/application.d.ts

@@ -39,11 +39,19 @@ export declare class Application extends ChildableComponent<Application, Abstrac
     logger: Logger;
     options: Options;
     /** @internal */
-    loggerType: string | Function;
+    readonly loggerType: string | Function;
+    /** @internal */
+    readonly skipErrorChecking: boolean;
     /**
      * The version number of TypeDoc.
      */
     static VERSION: string;
+    /**
+     * Emitted after plugins have been loaded and options have been read, but before they have been frozen.
+     * The listener will be given an instance of {@link Application} and the {@link TypeDocOptions | Partial<TypeDocOptions>}
+     * passed to `bootstrap`.
+     */
+    static readonly EVENT_BOOTSTRAP_END: string;
     /**
      * Create a new TypeDoc application instance.
      *

package/dist/lib/application.js

@@ -24,6 +24,7 @@ const general_1 = require("./utils/general");
 const exports_1 = require("./validation/exports");
 const documentation_1 = require("./validation/documentation");
 const links_1 = require("./validation/links");
+const application_events_1 = require("./application-events");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const packageInfo = require("../../package.json");
 const supportedVersionMajorMinor = packageInfo.peerDependencies.typescript
@@ -96,8 +97,9 @@ let Application = Application_1 = class Application extends component_1.Childabl
         }
         this.options.read(this.logger);
         if ((0, general_1.hasBeenLoadedMultipleTimes)()) {
-            this.logger.warn(`TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc. This will likely break things.`);
+            this.logger.warn(`TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc. The loaded paths are:\n\t${(0, general_1.getLoadedPaths)().join("\n\t")}`);
         }
+        this.trigger(application_events_1.ApplicationEvents.BOOTSTRAP_END, this, options);
     }
     /**
      * Return the path to the TypeScript compiler.
@@ -136,10 +138,12 @@ let Application = Application_1 = class Application extends component_1.Childabl
         }
         const programs = (0, array_1.unique)(entryPoints.map((e) => e.program));
         this.logger.verbose(`Converting with ${programs.length} programs ${entryPoints.length} entry points`);
-        const errors = programs.flatMap((program) => ts.getPreEmitDiagnostics(program));
-        if (errors.length) {
-            this.logger.diagnostics(errors);
-            return;
+        if (this.skipErrorChecking === false) {
+            const errors = programs.flatMap((program) => ts.getPreEmitDiagnostics(program));
+            if (errors.length) {
+                this.logger.diagnostics(errors);
+                return;
+            }
         }
         if (this.options.getValue("emit") === "both") {
             for (const program of programs) {
@@ -302,9 +306,18 @@ let Application = Application_1 = class Application extends component_1.Childabl
  * The version number of TypeDoc.
  */
 Application.VERSION = packageInfo.version;
+/**
+ * Emitted after plugins have been loaded and options have been read, but before they have been frozen.
+ * The listener will be given an instance of {@link Application} and the {@link TypeDocOptions | Partial<TypeDocOptions>}
+ * passed to `bootstrap`.
+ */
+Application.EVENT_BOOTSTRAP_END = application_events_1.ApplicationEvents.BOOTSTRAP_END;
 __decorate([
     (0, utils_1.BindOption)("logger")
 ], Application.prototype, "loggerType", void 0);
+__decorate([
+    (0, utils_1.BindOption)("skipErrorChecking")
+], Application.prototype, "skipErrorChecking", void 0);
 Application = Application_1 = __decorate([
     (0, component_1.Component)({ name: "application", internal: true })
 ], Application);

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

@@ -29,6 +29,9 @@ function resolveDeclarationReference(reflection, ref) {
             if (refl.kindOf(models_1.ReflectionKind.ExportContainer)) {
                 high.push(refl);
             }
+            else {
+                low.push(refl);
+            }
         }
         if (reflection.kindOf(models_1.ReflectionKind.SomeMember)) {
             high.push(reflection.parent);
@@ -38,7 +41,12 @@ function resolveDeclarationReference(reflection, ref) {
             high.push(reflection.parent.parent);
         }
         else if (high[0] !== reflection) {
-            high.push(reflection);
+            if (reflection.parent instanceof models_1.ContainerReflection) {
+                high.push(...(reflection.parent.children?.filter((c) => c.name === reflection.name) || []));
+            }
+            else {
+                high.push(reflection);
+            }
         }
     }
     if (ref.symbolReference) {

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

@@ -54,6 +54,8 @@ const wantedKinds = {
         ts.SyntaxKind.PropertySignature,
         ts.SyntaxKind.BinaryExpression,
         ts.SyntaxKind.PropertyAssignment,
+        // class X { constructor(/** Comment */ readonly z: any) }
+        ts.SyntaxKind.Parameter,
     ],
     [models_1.ReflectionKind.Method]: [
         ts.SyntaxKind.FunctionDeclaration,

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

@@ -8,6 +8,13 @@ const blockLexer_1 = require("./blockLexer");
 const discovery_1 = require("./discovery");
 const lineLexer_1 = require("./lineLexer");
 const parser_1 = require("./parser");
+const jsDocCommentKinds = [
+    ts.SyntaxKind.JSDocPropertyTag,
+    ts.SyntaxKind.JSDocCallbackTag,
+    ts.SyntaxKind.JSDocTypedefTag,
+    ts.SyntaxKind.JSDocTemplateTag,
+    ts.SyntaxKind.JSDocEnumTag,
+];
 const commentCache = new WeakMap();
 function getCommentWithCache(discovered, config, logger) {
     if (!discovered)
@@ -52,6 +59,11 @@ function getCommentImpl(commentSource, config, logger, moduleComment) {
     return comment;
 }
 function getComment(symbol, kind, config, logger, commentStyle) {
+    if (symbol
+        .getDeclarations()
+        ?.every((d) => jsDocCommentKinds.includes(d.kind))) {
+        return getJsDocComment(symbol.declarations[0], config, logger);
+    }
     return getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, commentStyle), config, logger, symbol.declarations?.some(ts.isSourceFile) || false);
 }
 exports.getComment = getComment;
@@ -106,7 +118,7 @@ function getJsDocComment(declaration, config, logger) {
         logger.error(`Failed to find JSDoc tag for ${name} after parsing comment, please file a bug report.`, declaration);
     }
     else {
-        return new models_1.Comment(tag.content.slice());
+        return new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
     }
 }
 exports.getJsDocComment = getJsDocComment;

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

@@ -0,0 +1,4 @@
+import { Comment, CommentDisplayPart, Reflection } from "../../models";
+import type { Logger, ValidationOptions } from "../../utils";
+export declare function resolveLinks(comment: Comment, reflection: Reflection, validation: ValidationOptions, logger: Logger): void;
+export declare function resolvePartLinks(reflection: Reflection, parts: readonly CommentDisplayPart[], warn: () => void, validation: ValidationOptions, logger: Logger): CommentDisplayPart[];

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

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePartLinks = exports.resolveLinks = void 0;
+const ts = require("typescript");
+const models_1 = require("../../models");
+const declarationReference_1 = require("./declarationReference");
+const declarationReferenceResolver_1 = require("./declarationReferenceResolver");
+const urlPrefix = /^(http|ftp)s?:\/\//;
+const brackets = /\[\[(?!include:)([^\]]+)\]\]/g;
+function resolveLinks(comment, reflection, validation, logger) {
+    let warned = false;
+    const warn = () => {
+        if (!warned) {
+            warned = true;
+            logger.warn(`${reflection.getFriendlyFullName()}: Comment [[target]] style links are deprecated and will be removed in 0.24`);
+        }
+    };
+    comment.summary = resolvePartLinks(reflection, comment.summary, warn, validation, logger);
+    for (const tag of comment.blockTags) {
+        tag.content = resolvePartLinks(reflection, tag.content, warn, validation, logger);
+    }
+    if (reflection instanceof models_1.DeclarationReflection && reflection.readme) {
+        reflection.readme = resolvePartLinks(reflection, reflection.readme, warn, validation, logger);
+    }
+}
+exports.resolveLinks = resolveLinks;
+function resolvePartLinks(reflection, parts, warn, validation, logger) {
+    return parts.flatMap((part) => processPart(reflection, part, warn, validation, logger));
+}
+exports.resolvePartLinks = resolvePartLinks;
+function processPart(reflection, part, warn, validation, logger) {
+    if (part.kind === "text" && brackets.test(part.text)) {
+        warn();
+        return replaceBrackets(reflection, part.text, validation, logger);
+    }
+    if (part.kind === "inline-tag") {
+        if (part.tag === "@link" ||
+            part.tag === "@linkcode" ||
+            part.tag === "@linkplain") {
+            return resolveLinkTag(reflection, part, (msg) => {
+                if (validation.invalidLink) {
+                    logger.warn(msg);
+                }
+            });
+        }
+    }
+    return part;
+}
+function resolveLinkTag(reflection, part, warn) {
+    let pos = 0;
+    const end = part.text.length;
+    while (pos < end && ts.isWhiteSpaceLike(part.text.charCodeAt(pos))) {
+        pos++;
+    }
+    const origText = part.text;
+    // Try to parse one
+    const declRef = (0, declarationReference_1.parseDeclarationReference)(part.text, pos, end);
+    let target;
+    if (declRef) {
+        // Got one, great! Try to resolve the link
+        target = (0, declarationReferenceResolver_1.resolveDeclarationReference)(reflection, declRef[0]);
+        pos = declRef[1];
+    }
+    if (!target) {
+        if (urlPrefix.test(part.text)) {
+            const wsIndex = part.text.search(/\s/);
+            target =
+                wsIndex === -1 ? part.text : part.text.substring(0, wsIndex);
+            pos = target.length;
+        }
+    }
+    // If resolution via a declaration reference failed, revert to the legacy "split and check"
+    // method... this should go away in 0.24, once people have had a chance to migrate any failing links.
+    if (!target) {
+        const resolved = legacyResolveLinkTag(reflection, part);
+        if (resolved) {
+            warn(`Failed to resolve {@link ${origText}} in ${reflection.getFriendlyFullName()} with declaration references. This link will break in v0.24.`);
+        }
+        return resolved;
+    }
+    // Remaining text after an optional pipe is the link text, so advance
+    // until that's consumed.
+    while (pos < end && ts.isWhiteSpaceLike(part.text.charCodeAt(pos))) {
+        pos++;
+    }
+    if (pos < end && part.text[pos] === "|") {
+        pos++;
+    }
+    part.target = target;
+    part.text =
+        part.text.substring(pos).trim() ||
+            (typeof target === "string" ? target : target.name);
+    return part;
+}
+function legacyResolveLinkTag(reflection, part) {
+    const { caption, target } = splitLinkText(part.text);
+    if (urlPrefix.test(target)) {
+        part.text = caption;
+        part.target = target;
+    }
+    else {
+        const targetRefl = reflection.findReflectionByName(target);
+        if (targetRefl) {
+            part.text = caption;
+            part.target = targetRefl;
+        }
+    }
+    return part;
+}
+function replaceBrackets(reflection, text, validation, logger) {
+    const parts = [];
+    let begin = 0;
+    brackets.lastIndex = 0;
+    for (const match of text.matchAll(brackets)) {
+        if (begin != match.index) {
+            parts.push({
+                kind: "text",
+                text: text.substring(begin, match.index),
+            });
+        }
+        begin = match.index + match[0].length;
+        const content = match[1];
+        const { target, caption } = splitLinkText(content);
+        if (urlPrefix.test(target)) {
+            parts.push({
+                kind: "inline-tag",
+                tag: "@link",
+                text: caption,
+                target,
+            });
+        }
+        else {
+            const targetRefl = reflection.findReflectionByName(target);
+            if (targetRefl) {
+                parts.push({
+                    kind: "inline-tag",
+                    tag: "@link",
+                    text: caption,
+                    target: targetRefl,
+                });
+            }
+            else {
+                if (validation.invalidLink) {
+                    logger.warn("Failed to find target: " + content);
+                }
+                parts.push({
+                    kind: "inline-tag",
+                    tag: "@link",
+                    text: content,
+                });
+            }
+        }
+    }
+    parts.push({
+        kind: "text",
+        text: text.substring(begin),
+    });
+    return parts;
+}
+/**
+ * Split the given link into text and target at first pipe or space.
+ *
+ * @param text  The source string that should be checked for a split character.
+ * @returns An object containing the link text and target.
+ */
+function splitLinkText(text) {
+    let splitIndex = text.indexOf("|");
+    if (splitIndex === -1) {
+        splitIndex = text.search(/\s/);
+    }
+    if (splitIndex !== -1) {
+        return {
+            caption: text
+                .substring(splitIndex + 1)
+                .replace(/\n+/, " ")
+                .trim(),
+            target: text.substring(0, splitIndex).trim(),
+        };
+    }
+    else {
+        return {
+            caption: text,
+            target: text,
+        };
+    }
+}

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

@@ -1,13 +1,13 @@
 import * as ts from "typescript";
 import type { Application } from "../application";
-import { ProjectReflection, SomeType } from "../models/index";
+import { Comment, CommentDisplayPart, ProjectReflection, Reflection, SomeType } from "../models/index";
 import { Context } from "./context";
 import { ConverterComponent } from "./components";
 import { ChildableComponent } from "../utils/component";
 import { MinimalSourceFile } from "../utils";
 import type { DocumentationEntryPoint } from "../utils/entry-point";
 import { CommentParserConfig } from "./comments";
-import type { CommentStyle } from "../utils/options/declaration";
+import type { CommentStyle, ValidationOptions } from "../utils/options/declaration";
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
@@ -24,6 +24,8 @@ export declare class Converter extends ChildableComponent<Application, Converter
     excludePrivate: boolean;
     excludeProtected: boolean;
     commentStyle: CommentStyle;
+    /** @internal */
+    validation: ValidationOptions;
     private _config?;
     get config(): CommentParserConfig;
     /**
@@ -108,7 +110,9 @@ export declare class Converter extends ChildableComponent<Application, Converter
     /**
      * Parse the given file into a comment. Intended to be used with markdown files.
      */
-    parseRawComment(file: MinimalSourceFile): import("../models/index").Comment;
+    parseRawComment(file: MinimalSourceFile): Comment;
+    resolveLinks(comment: Comment, owner: Reflection): void;
+    resolveLinks(parts: readonly CommentDisplayPart[], owner: Reflection): CommentDisplayPart[];
     /**
      * Compile the files within the given context and convert the compiler symbols to reflections.
      *

package/dist/lib/converter/converter.js

@@ -22,6 +22,7 @@ const enum_1 = require("../utils/enum");
 const comments_1 = require("./comments");
 const parser_1 = require("./comments/parser");
 const rawLexer_1 = require("./comments/rawLexer");
+const linkResolver_1 = require("./comments/linkResolver");
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
@@ -66,6 +67,21 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
     parseRawComment(file) {
         return (0, parser_1.parseComment)((0, rawLexer_1.lexCommentString)(file.text), this.config, file, this.application.logger);
     }
+    resolveLinks(comment, owner) {
+        if (comment instanceof index_1.Comment) {
+            (0, linkResolver_1.resolveLinks)(comment, owner, this.validation, this.owner.logger);
+        }
+        else {
+            let warned = false;
+            const warn = () => {
+                if (!warned) {
+                    warned = true;
+                    this.application.logger.warn(`${owner.name}: Comment [[target]] style links are deprecated and will be removed in 0.24`);
+                }
+            };
+            return (0, linkResolver_1.resolvePartLinks)(owner, comment, warn, this.validation, this.owner.logger);
+        }
+    }
     /**
      * Compile the files within the given context and convert the compiler symbols to reflections.
      *
@@ -267,6 +283,9 @@ __decorate([
 __decorate([
     (0, utils_1.BindOption)("commentStyle")
 ], Converter.prototype, "commentStyle", void 0);
+__decorate([
+    (0, utils_1.BindOption)("validation")
+], Converter.prototype, "validation", void 0);
 Converter = Converter_1 = __decorate([
     (0, component_1.Component)({
         name: "converter",

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

@@ -62,6 +62,7 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         if (declaration && ts.isJSDocParameterTag(declaration)) {
             paramRefl.comment = (0, comments_1.getJsDocComment)(declaration, context.converter.config, context.logger);
         }
+        paramRefl.comment || (paramRefl.comment = (0, comments_1.getComment)(param, paramRefl.kind, context.converter.config, context.logger, context.converter.commentStyle));
         context.registerReflection(paramRefl, param);
         context.trigger(converter_events_1.ConverterEvents.CREATE_PARAMETER, paramRefl);
         let type;

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

@@ -1,4 +1,3 @@
-import type { Reflection } from "../../models/reflections/abstract";
 import { ConverterComponent } from "../components";
 import type { Context } from "../../converter";
 import { ValidationOptions } from "../../utils";
@@ -11,25 +10,5 @@ export declare class LinkResolverPlugin extends ConverterComponent {
      * Create a new LinkResolverPlugin instance.
      */
     initialize(): void;
-    /**
-     * Find all old style double bracket references to symbols within the given text and transform them into a link.
-     *
-     * @param text  The text that should be parsed.
-     * @returns The text with symbol references replaced by links.
-     */
-    private replaceBrackets;
     onResolve(context: Context): void;
-    processReflection(reflection: Reflection): void;
-    private processParts;
-    private processPart;
-    /**
-     * Split the given link into text and target at first pipe or space.
-     *
-     * @param text  The source string that should be checked for a split character.
-     * @returns An object containing the link text and target.
-     */
-    static splitLinkText(text: string): {
-        caption: string;
-        target: string;
-    };
 }