typedoc 0.27.6 → 0.27.7

package/bin/typedoc

@@ -1,5 +1,24 @@
 #!/usr/bin/env node
 //@ts-check
 
-/* eslint-disable @typescript-eslint/no-var-requires */
-import("../dist/lib/cli.js");
+const { fork } = require("child_process");
+
+function main() {
+    fork(__dirname + "/../dist/lib/cli.js", process.argv.slice(2), {
+        stdio: "inherit",
+    }).on("exit", (code) => {
+        // Watch restart required? Fork a new child
+        if (code === 7) {
+            // Set an environment variable to ensure we continue watching
+            // Otherwise, the watch might stop unexpectedly if the watch
+            // option was set in a config file originally, and change to false
+            // later, causing a restart
+            process.env["TYPEDOC_FORCE_WATCH"] = "1";
+            main();
+        } else {
+            process.exit(code || 0);
+        }
+    });
+}
+
+main();

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export * as Configuration from "./lib/utils/options/index.js";
 export * from "./lib/models/index.js";
 export { Converter, Context, type CommentParserConfig, type DeclarationReference, type SymbolReference, type ComponentPath, type Meaning, type MeaningKeyword, type ExternalResolveResult, type ExternalSymbolResolver, type ConverterEvents, } from "./lib/converter/index.js";
 export { Renderer, DefaultTheme, DefaultThemeRenderContext, Slugger, UrlMapping, Theme, PageEvent, RendererEvent, MarkdownEvent, IndexEvent, } from "./lib/output/index.js";
-export type { RenderTemplate, RendererHooks, NavigationElement, RendererEvents, PageHeading, } from "./lib/output/index.js";
+export type { RenderTemplate, RendererHooks, NavigationElement, RendererEvents, PageHeading, Icons, } from "./lib/output/index.js";
 export { Outputs } from "./lib/output/output.js";
 export { ArgumentsReader, Option, CommentStyle, JSX, LogLevel, Logger, Options, OptionDefaults, PackageJsonReader, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, MinimalSourceFile, normalizePath, } from "./lib/utils/index.js";
 export type { OptionsReader, TypeDocOptions, TypeDocOptionMap, ValidationOptions, TypeDocOptionValues, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, ObjectDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, ManuallyValidatedOption, EnumKeys, JsDocCompatibility, OutputSpecification, } from "./lib/utils/index.js";

package/dist/lib/application.d.ts

@@ -137,7 +137,36 @@ export declare class Application extends AbstractComponent<Application, Applicat
      * @returns An instance of ProjectReflection on success, undefined otherwise.
      */
     convert(): Promise<ProjectReflection | undefined>;
-    convertAndWatch(success: (project: ProjectReflection) => Promise<void>): void;
+    private watchers;
+    private _watchFile?;
+    private criticalFiles;
+    private clearWatches;
+    private watchConfigFile;
+    /**
+     * Register that the current build depends on a file, so that in watch mode
+     * the build will be repeated.  Has no effect if a watch build is not
+     * running, or if the file has already been registered.
+     *
+     * @param path The file to watch.  It does not need to exist, and you should
+     * in fact register files you look for, but which do not exist, so that if
+     * they are created the build will re-run.  (e.g. if you look through a list
+     * of 5 possibilities and find the third, you should register the first 3.)
+     *
+     * @param shouldRestart Should the build be completely restarted?  (This is
+     * normally only used for configuration files -- i.e. files whose contents
+     * determine how conversion, rendering, or compiling will be done, as
+     * opposed to files that are only read *during* the conversion or
+     * rendering.)
+     */
+    watchFile(path: string, shouldRestart?: boolean): void;
+    /**
+     * Run a convert / watch process.
+     *
+     * @param success Callback to run after each convert, receiving the project
+     * @returns True if the watch process should be restarted due to a
+     * configuration change, false for an options error
+     */
+    convertAndWatch(success: (project: ProjectReflection) => Promise<void>): Promise<boolean>;
     validate(project: ProjectReflection): void;
     /**
      * Render outputs selected with options for the specified project

package/dist/lib/application.js

@@ -197,7 +197,6 @@ let Application = (() => {
                 throw new Error("An application handle must be retrieved with Application.bootstrap or Application.bootstrapWithPlugins");
             }
             super(null); // We own ourselves
-            __runInitializers(this, _entryPoints_extraInitializers);
             this.converter = new Converter(this);
             this.renderer = new Renderer(this);
             this.logger.i18n = this.i18n;
@@ -218,7 +217,7 @@ let Application = (() => {
             readers.forEach((r) => app.options.addReader(r));
             app.options.reset();
             app.setOptions(options, /* reportErrors */ false);
-            await app.options.read(new Logger());
+            await app.options.read(new Logger(), undefined, (path) => app.watchConfigFile(path));
             app.logger.level = app.options.getValue("logLevel");
             await loadPlugins(app, app.options.getValue("plugin"));
             await app._bootstrap(options);
@@ -245,7 +244,7 @@ let Application = (() => {
         async _bootstrap(options) {
             this.options.reset();
             this.setOptions(options, /* reportErrors */ false);
-            await this.options.read(this.logger);
+            await this.options.read(this.logger, undefined, (path) => this.watchConfigFile(path));
             this.setOptions(options);
             this.logger.level = this.options.getValue("logLevel");
             for (const [lang, locales] of Object.entries(this.options.getValue("locales"))) {
@@ -257,13 +256,18 @@ let Application = (() => {
             this.trigger(ApplicationEvents.BOOTSTRAP_END, this);
             if (!this.internationalization.hasTranslations(this.lang)) {
                 // Not internationalized as by definition we don't know what to include here.
-                this.logger.warn(`Options specified "${this.lang}" as the language to use, but TypeDoc does not support it.`);
-                this.logger.info(("The supported languages are:\n\t" +
+                this.logger.warn(`Options specified "${this.lang}" as the language to use, but TypeDoc cannot provide translations for it.`);
+                this.logger.info(("The languages that translations are available for are:\n\t" +
                     this.internationalization
                         .getSupportedLanguages()
                         .join("\n\t")));
                 this.logger.info("You can define/override local locales with the `locales` option, or contribute them to TypeDoc!");
             }
+            else if (this.lang === "jp") {
+                this.logger.warn(
+                // Only Japanese see this. Meaning: "jp" is going to be removed in the future. Please designate "ja" instead.
+                "「jp」は将来削除されます。代わりに「ja」を指定してください。");
+            }
             if (this.options.getValue("useHostedBaseUrlForAbsoluteLinks") &&
                 !this.options.getValue("hostedBaseUrl")) {
                 this.logger.warn(this.i18n.useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl());
@@ -352,7 +356,43 @@ let Application = (() => {
             this.logger.verbose(`Finished conversion in ${Date.now() - startConversion}ms`);
             return project;
         }
-        convertAndWatch(success) {
+        watchers = (__runInitializers(this, _entryPoints_extraInitializers), new Map());
+        _watchFile;
+        criticalFiles = new Set();
+        clearWatches() {
+            this.watchers.forEach((w) => w.close());
+            this.watchers.clear();
+        }
+        watchConfigFile(path) {
+            this.criticalFiles.add(path);
+        }
+        /**
+         * Register that the current build depends on a file, so that in watch mode
+         * the build will be repeated.  Has no effect if a watch build is not
+         * running, or if the file has already been registered.
+         *
+         * @param path The file to watch.  It does not need to exist, and you should
+         * in fact register files you look for, but which do not exist, so that if
+         * they are created the build will re-run.  (e.g. if you look through a list
+         * of 5 possibilities and find the third, you should register the first 3.)
+         *
+         * @param shouldRestart Should the build be completely restarted?  (This is
+         * normally only used for configuration files -- i.e. files whose contents
+         * determine how conversion, rendering, or compiling will be done, as
+         * opposed to files that are only read *during* the conversion or
+         * rendering.)
+         */
+        watchFile(path, shouldRestart = false) {
+            this._watchFile?.(path, shouldRestart);
+        }
+        /**
+         * Run a convert / watch process.
+         *
+         * @param success Callback to run after each convert, receiving the project
+         * @returns True if the watch process should be restarted due to a
+         * configuration change, false for an options error
+         */
+        async convertAndWatch(success) {
             if (!this.options.getValue("preserveWatchOutput") &&
                 this.logger instanceof ConsoleLogger) {
                 ts.sys.clearScreen?.();
@@ -368,20 +408,20 @@ let Application = (() => {
             // have reported in the first time... just error out for now. I'm not convinced anyone will actually notice.
             if (this.options.getFileNames().length === 0) {
                 this.logger.error(this.i18n.solution_not_supported_in_watch_mode());
-                return;
+                return false;
             }
             // Support for packages mode is currently unimplemented
             if (this.entryPointStrategy !== EntryPointStrategy.Resolve &&
                 this.entryPointStrategy !== EntryPointStrategy.Expand) {
                 this.logger.error(this.i18n.strategy_not_supported_in_watch_mode());
-                return;
+                return false;
             }
             const tsconfigFile = findTsConfigFile(this.options.getValue("tsconfig")) ??
                 "tsconfig.json";
             // We don't want to do it the first time to preserve initial debug status messages. They'll be lost
             // after the user saves a file, but better than nothing...
             let firstStatusReport = true;
-            const host = ts.createWatchCompilerHost(tsconfigFile, {}, ts.sys, ts.createEmitAndSemanticDiagnosticsBuilderProgram, (diagnostic) => this.logger.diagnostic(diagnostic), (status, newLine, _options, errorCount) => {
+            const host = ts.createWatchCompilerHost(tsconfigFile, this.options.fixCompilerOptions({}), ts.sys, ts.createEmitAndSemanticDiagnosticsBuilderProgram, (diagnostic) => this.logger.diagnostic(diagnostic), (status, newLine, _options, errorCount) => {
                 if (!firstStatusReport &&
                     errorCount === void 0 &&
                     !this.options.getValue("preserveWatchOutput") &&
@@ -393,20 +433,59 @@ let Application = (() => {
             });
             let successFinished = true;
             let currentProgram;
+            let lastProgram = currentProgram;
+            let restarting = false;
+            this._watchFile = (path, shouldRestart = false) => {
+                this.logger.verbose(`Watching ${nicePath(path)}, shouldRestart=${shouldRestart}`);
+                if (this.watchers.has(path))
+                    return;
+                this.watchers.set(path, host.watchFile(path, (file) => {
+                    if (shouldRestart) {
+                        restartMain(file);
+                    }
+                    else if (!currentProgram) {
+                        currentProgram = lastProgram;
+                        this.logger.info(this.i18n.file_0_changed_rebuilding(nicePath(file)));
+                    }
+                    if (successFinished)
+                        runSuccess();
+                }, 2000));
+            };
+            /** resolver for the returned promise  */
+            let exitWatch;
+            const restartMain = (file) => {
+                if (restarting)
+                    return;
+                this.logger.info(this.i18n.file_0_changed_restarting(nicePath(file)));
+                restarting = true;
+                currentProgram = undefined;
+                this.clearWatches();
+                tsWatcher.close();
+            };
             const runSuccess = () => {
+                if (restarting && successFinished) {
+                    successFinished = false;
+                    exitWatch(true);
+                    return;
+                }
                 if (!currentProgram) {
                     return;
                 }
                 if (successFinished) {
-                    if (this.options.getValue("emit") === "both") {
+                    if (this.options.getValue("emit") === "both" &&
+                        currentProgram !== lastProgram) {
                         currentProgram.emit();
                     }
+                    // Save for possible re-run due to non-.ts file change
+                    lastProgram = currentProgram;
                     this.logger.resetErrors();
                     this.logger.resetWarnings();
                     const entryPoints = getWatchEntryPoints(this.logger, this.options, currentProgram);
                     if (!entryPoints) {
                         return;
                     }
+                    this.clearWatches();
+                    this.criticalFiles.forEach((path) => this.watchFile(path, true));
                     const project = this.converter.convert(entryPoints);
                     currentProgram = undefined;
                     successFinished = false;
@@ -416,23 +495,20 @@ let Application = (() => {
                     });
                 }
             };
-            const origCreateProgram = host.createProgram;
-            host.createProgram = (rootNames, options, host, oldProgram, configDiagnostics, references) => {
-                // If we always do this, we'll get a crash the second time a program is created.
-                if (rootNames !== undefined) {
-                    options = this.options.fixCompilerOptions(options || {});
-                }
-                return origCreateProgram(rootNames, options, host, oldProgram, configDiagnostics, references);
-            };
             const origAfterProgramCreate = host.afterProgramCreate;
             host.afterProgramCreate = (program) => {
-                if (ts.getPreEmitDiagnostics(program.getProgram()).length === 0) {
+                if (!restarting &&
+                    ts.getPreEmitDiagnostics(program.getProgram()).length === 0) {
                     currentProgram = program.getProgram();
                     runSuccess();
                 }
                 origAfterProgramCreate?.(program);
             };
-            ts.createWatchProgram(host);
+            const tsWatcher = ts.createWatchProgram(host);
+            // Don't return to caller until the watch needs to restart
+            return await new Promise((res) => {
+                exitWatch = res;
+            });
         }
         validate(project) {
             const checks = this.options.getValue("validation");

package/dist/lib/cli.js

@@ -25,8 +25,8 @@ async function main() {
         if (exitCode !== ExitCodes.Watching) {
             app.logger.verbose(`Full run took ${Date.now() - start}ms`);
             logRunSummary(app.logger);
-            process.exit(exitCode);
         }
+        process.exit(exitCode);
     }
     catch (error) {
         console.error("TypeDoc exiting with unexpected error:");
@@ -57,12 +57,12 @@ async function run(app) {
         app.logger.hasWarnings()) {
         return ExitCodes.OptionError;
     }
-    if (app.options.getValue("watch")) {
-        app.convertAndWatch(async (project) => {
+    if (app.options.getValue("watch") || process.env["TYPEDOC_FORCE_WATCH"]) {
+        const continueWatching = await app.convertAndWatch(async (project) => {
             app.validate(project);
             await app.generateOutputs(project);
         });
-        return ExitCodes.Watching;
+        return continueWatching ? ExitCodes.Watching : ExitCodes.OptionError;
     }
     const project = await app.convert();
     if (!project) {

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

@@ -47,8 +47,6 @@ export declare class Converter extends AbstractComponent<Application, ConverterE
     /** @internal */
     accessor excludeExternals: boolean;
     /** @internal */
-    accessor excludeNotDocumented: boolean;
-    /** @internal */
     accessor excludePrivate: boolean;
     /** @internal */
     accessor excludeProtected: boolean;
@@ -163,7 +161,8 @@ export declare class Converter extends AbstractComponent<Application, ConverterE
      * @returns The TypeDoc type reflection representing the given node and type.
      * @internal
      */
-    convertType(context: Context, node: ts.TypeNode | ts.Type | undefined): SomeType;
+    convertType(context: Context, node: ts.TypeNode | undefined): SomeType;
+    convertType(context: Context, type: ts.Type, node?: ts.TypeNode): SomeType;
     /**
      * Parse the given file into a comment. Intended to be used with markdown files.
      */

package/dist/lib/converter/converter.js

@@ -72,9 +72,6 @@ let Converter = (() => {
     let _excludeExternals_decorators;
     let _excludeExternals_initializers = [];
     let _excludeExternals_extraInitializers = [];
-    let _excludeNotDocumented_decorators;
-    let _excludeNotDocumented_initializers = [];
-    let _excludeNotDocumented_extraInitializers = [];
     let _excludePrivate_decorators;
     let _excludePrivate_initializers = [];
     let _excludePrivate_extraInitializers = [];
@@ -104,7 +101,6 @@ let Converter = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _externalPattern_decorators = [Option("externalPattern")];
             _excludeExternals_decorators = [Option("excludeExternals")];
-            _excludeNotDocumented_decorators = [Option("excludeNotDocumented")];
             _excludePrivate_decorators = [Option("excludePrivate")];
             _excludeProtected_decorators = [Option("excludeProtected")];
             _excludeReferences_decorators = [Option("excludeReferences")];
@@ -115,7 +111,6 @@ let Converter = (() => {
             _maxTypeConversionDepth_decorators = [Option("maxTypeConversionDepth")];
             __esDecorate(this, 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, _externalPattern_extraInitializers);
             __esDecorate(this, 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, _excludeExternals_extraInitializers);
-            __esDecorate(this, 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, _excludeNotDocumented_extraInitializers);
             __esDecorate(this, null, _excludePrivate_decorators, { kind: "accessor", name: "excludePrivate", static: false, private: false, access: { has: obj => "excludePrivate" in obj, get: obj => obj.excludePrivate, set: (obj, value) => { obj.excludePrivate = value; } }, metadata: _metadata }, _excludePrivate_initializers, _excludePrivate_extraInitializers);
             __esDecorate(this, null, _excludeProtected_decorators, { kind: "accessor", name: "excludeProtected", static: false, private: false, access: { has: obj => "excludeProtected" in obj, get: obj => obj.excludeProtected, set: (obj, value) => { obj.excludeProtected = value; } }, metadata: _metadata }, _excludeProtected_initializers, _excludeProtected_extraInitializers);
             __esDecorate(this, null, _excludeReferences_decorators, { kind: "accessor", name: "excludeReferences", static: false, private: false, access: { has: obj => "excludeReferences" in obj, get: obj => obj.excludeReferences, set: (obj, value) => { obj.excludeReferences = value; } }, metadata: _metadata }, _excludeReferences_initializers, _excludeReferences_extraInitializers);
@@ -136,11 +131,7 @@ let Converter = (() => {
         /** @internal */
         get excludeExternals() { return this.#excludeExternals_accessor_storage; }
         set excludeExternals(value) { this.#excludeExternals_accessor_storage = value; }
-        #excludeNotDocumented_accessor_storage = (__runInitializers(this, _excludeExternals_extraInitializers), __runInitializers(this, _excludeNotDocumented_initializers, void 0));
-        /** @internal */
-        get excludeNotDocumented() { return this.#excludeNotDocumented_accessor_storage; }
-        set excludeNotDocumented(value) { this.#excludeNotDocumented_accessor_storage = value; }
-        #excludePrivate_accessor_storage = (__runInitializers(this, _excludeNotDocumented_extraInitializers), __runInitializers(this, _excludePrivate_initializers, void 0));
+        #excludePrivate_accessor_storage = (__runInitializers(this, _excludeExternals_extraInitializers), __runInitializers(this, _excludePrivate_initializers, void 0));
         /** @internal */
         get excludePrivate() { return this.#excludePrivate_accessor_storage; }
         set excludePrivate(value) { this.#excludePrivate_accessor_storage = value; }
@@ -334,15 +325,8 @@ let Converter = (() => {
         convertSymbol(context, symbol, exportSymbol) {
             convertSymbol(context, symbol, exportSymbol);
         }
-        /**
-         * Convert the given TypeScript type into its TypeDoc type reflection.
-         *
-         * @param context  The context object describing the current state the converter is in.
-         * @returns The TypeDoc type reflection representing the given node and type.
-         * @internal
-         */
-        convertType(context, node) {
-            return convertType(context, node);
+        convertType(context, typeOrNode, maybeNode) {
+            return convertType(context, typeOrNode, maybeNode);
         }
         /**
          * Parse the given file into a comment. Intended to be used with markdown files.
@@ -487,7 +471,17 @@ let Converter = (() => {
         isExternal(symbol) {
             this.externalPatternCache ??= createMinimatch(this.externalPattern);
             const cache = this.externalPatternCache;
-            return (symbol.getDeclarations() ?? []).some((node) => matchesAny(cache, node.getSourceFile().fileName));
+            const declarations = symbol.getDeclarations();
+            // `undefined` has no declarations, if someone does `export default undefined`
+            // the symbol ends up as having no declarations (the export symbol does, but
+            // not the source symbol)
+            if (!declarations?.length) {
+                return false;
+            }
+            // If there are any non-external declarations, treat it as non-external
+            // This is possible with declaration merging against external namespaces
+            // (e.g. merging with HTMLElementTagNameMap)
+            return declarations.every((node) => matchesAny(cache, node.getSourceFile().fileName));
         }
         processDocumentTags(reflection, parent) {
             let relativeTo = reflection.comment?.sourcePath;
@@ -515,6 +509,7 @@ let Converter = (() => {
             const children = frontmatter["children"];
             delete frontmatter["children"];
             const docRefl = new DocumentReflection(displayName, parent, content, frontmatter);
+            this.application.watchFile(file.fileName);
             parent.addChild(docRefl);
             parent.project.registerReflection(docRefl, undefined, file.fileName);
             this.trigger(ConverterEvents.CREATE_DOCUMENT, undefined, docRefl);

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

@@ -50,9 +50,11 @@ export function createSignature(context, kind, signature, symbol, declaration) {
         sigRef.type = new IntrinsicType("this");
     }
     else {
-        sigRef.type = context.converter.convertType(sigRefCtx, (declaration?.kind === ts.SyntaxKind.FunctionDeclaration &&
-            declaration.type) ||
-            signature.getReturnType());
+        let typeNode = declaration?.type;
+        if (typeNode && ts.isJSDocReturnTag(typeNode)) {
+            typeNode = typeNode.typeExpression?.type;
+        }
+        sigRef.type = context.converter.convertType(sigRefCtx, signature.getReturnType(), typeNode);
     }
     context.registerReflection(sigRef, undefined);
     switch (kind) {
@@ -106,8 +108,15 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         context.registerReflection(paramRefl, param);
         context.converter.trigger(ConverterEvents.CREATE_PARAMETER, context, paramRefl);
         let type;
+        let typeNode;
         if (declaration) {
             type = context.checker.getTypeOfSymbolAtLocation(param, declaration);
+            if (ts.isParameter(declaration)) {
+                typeNode = declaration.type;
+            }
+            else {
+                typeNode = declaration.typeExpression?.type;
+            }
         }
         else {
             type = param.type;
@@ -117,8 +126,11 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
             declaration.type?.kind === ts.SyntaxKind.ThisType) {
             paramRefl.type = new IntrinsicType("this");
         }
+        else if (!type) {
+            paramRefl.type = new IntrinsicType("any");
+        }
         else {
-            paramRefl.type = context.converter.convertType(context.withScope(paramRefl), type);
+            paramRefl.type = context.converter.convertType(context.withScope(paramRefl), type, typeNode);
         }
         let isOptional = false;
         if (declaration) {

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

@@ -9,4 +9,6 @@ export declare class IncludePlugin extends ConverterComponent {
     constructor(owner: Converter);
     private onCreate;
     checkIncludeTagsParts(refl: Reflection, relative: string, parts: CommentDisplayPart[], included?: string[]): void;
+    getRegions(refl: Reflection, file: string, ext: string, textPart: string, text: string, regionTargets: string, tag: string, ignoreIndent: boolean): string;
+    getLines(refl: Reflection, file: string, textPart: string, text: string, requestedLines: string, tag: string): string;
 }