typedoc 0.27.7 → 0.27.9

package/dist/lib/application.js

@@ -520,7 +520,7 @@ let Application = (() => {
                 validateExports(project, this.logger, this.options.getValue("intentionallyNotExported"));
             }
             if (checks.notDocumented) {
-                validateDocumentation(project, this.logger, this.options.getValue("requiredToBeDocumented"));
+                validateDocumentation(project, this.logger, this.options.getValue("requiredToBeDocumented"), this.options.getValue("intentionallyNotDocumented"));
             }
             if (checks.invalidLink) {
                 validateLinks(project, this.logger);

package/dist/lib/internationalization/internationalization.js

@@ -226,6 +226,8 @@ export class Internationalization {
                 .map((x) => x.substring(0, x.indexOf(".")))
                 .filter((x) => x !== "jp"),
             ...this.allTranslations.keys(),
-        ]).sort();
+        ])
+            .filter((lang) => this.hasTranslations(lang))
+            .sort();
     }
 }

package/dist/lib/internationalization/locales/en.cjs

@@ -61,6 +61,7 @@ module.exports = {
     failed_to_resolve_link_to_0_in_document_1_may_have_meant_2: `Failed to resolve link to "{0}" in document {1}. You may have wanted "{2}"`,
     type_0_defined_in_1_is_referenced_by_2_but_not_included_in_docs: `{0}, defined in {1}, is referenced by {2} but not included in the documentation`,
     reflection_0_kind_1_defined_in_2_does_not_have_any_documentation: `{0} ({1}), defined in {2}, does not have any documentation`,
+    invalid_intentionally_not_documented_names_0: "The following qualified reflection names were marked as intentionally not documented, but were either not referenced in the documentation, or were documented:\n\t{0}",
     invalid_intentionally_not_exported_symbols_0: "The following symbols were marked as intentionally not exported, but were either not referenced in the documentation, or were exported:\n\t{0}",
     reflection_0_has_unused_mergeModuleWith_tag: "{0} has a @mergeModuleWith tag which could not be resolved",
     reflection_0_links_to_1_with_text_2_but_resolved_to_3: `"{0}" links to "{1}" with text "{2}" which exists but does not have a link in the documentation, will link to "{3}" instead.`,
@@ -217,6 +218,7 @@ module.exports = {
     help_searchGroupBoosts: 'Configure search to give a relevance boost to selected kinds (eg "class")',
     help_useFirstParagraphOfCommentAsSummary: "If set and no @summary tag is specified, TypeDoc will use the first paragraph of comments as the short summary in the module/namespace view",
     help_jsDocCompatibility: "Sets compatibility options for comment parsing that increase similarity with JSDoc comments",
+    help_suppressCommentWarningsInDeclarationFiles: "Prevents warnings due to unspecified tags from being reported in comments within .d.ts files.",
     help_commentStyle: "Determines how TypeDoc searches for comments",
     help_useTsLinkResolution: "Use TypeScript's link resolution when determining where @link tags point. This only applies to JSDoc style comments",
     help_preserveLinkText: "If set, @link tags without link text will use the text content as the link. If not set, will use the target reflection name",
@@ -243,6 +245,7 @@ module.exports = {
     help_treatValidationWarningsAsErrors: "If set, warnings emitted during validation will be treated as errors. This option cannot be used to disable treatWarningsAsErrors for validation warnings",
     help_intentionallyNotExported: "A list of types which should not produce 'referenced but not documented' warnings",
     help_requiredToBeDocumented: "A list of reflection kinds that must be documented",
+    help_intentionallyNotDocumented: "A list of full reflection names which should not produce warnings about not being documented",
     help_validation: "Specify which validation steps TypeDoc should perform on your generated documentation",
     // ==================================================================
     // Option validation
@@ -262,7 +265,7 @@ module.exports = {
     highlightLanguages_contains_invalid_languages_0: "highlightLanguages contains invalid languages: {0}, run typedoc --help for a list of supported languages",
     hostedBaseUrl_must_start_with_http: "hostedBaseUrl must start with http:// or https://",
     useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set",
-    favicon_must_have_one_of_the_following_extensions_0: "Favicon must have on of the following extensions: {0}",
+    favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object",
     option_0_must_be_a_function: "The '{0}' option must be a function",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values`,

package/dist/lib/internationalization/locales/en.d.cts

@@ -56,6 +56,7 @@ declare const _default: {
     readonly failed_to_resolve_link_to_0_in_document_1_may_have_meant_2: "Failed to resolve link to \"{0}\" in document {1}. You may have wanted \"{2}\"";
     readonly type_0_defined_in_1_is_referenced_by_2_but_not_included_in_docs: "{0}, defined in {1}, is referenced by {2} but not included in the documentation";
     readonly reflection_0_kind_1_defined_in_2_does_not_have_any_documentation: "{0} ({1}), defined in {2}, does not have any documentation";
+    readonly invalid_intentionally_not_documented_names_0: "The following qualified reflection names were marked as intentionally not documented, but were either not referenced in the documentation, or were documented:\n\t{0}";
     readonly invalid_intentionally_not_exported_symbols_0: "The following symbols were marked as intentionally not exported, but were either not referenced in the documentation, or were exported:\n\t{0}";
     readonly reflection_0_has_unused_mergeModuleWith_tag: "{0} has a @mergeModuleWith tag which could not be resolved";
     readonly reflection_0_links_to_1_with_text_2_but_resolved_to_3: "\"{0}\" links to \"{1}\" with text \"{2}\" which exists but does not have a link in the documentation, will link to \"{3}\" instead.";
@@ -204,6 +205,7 @@ declare const _default: {
     readonly help_searchGroupBoosts: "Configure search to give a relevance boost to selected kinds (eg \"class\")";
     readonly help_useFirstParagraphOfCommentAsSummary: "If set and no @summary tag is specified, TypeDoc will use the first paragraph of comments as the short summary in the module/namespace view";
     readonly help_jsDocCompatibility: "Sets compatibility options for comment parsing that increase similarity with JSDoc comments";
+    readonly help_suppressCommentWarningsInDeclarationFiles: "Prevents warnings due to unspecified tags from being reported in comments within .d.ts files.";
     readonly help_commentStyle: "Determines how TypeDoc searches for comments";
     readonly help_useTsLinkResolution: "Use TypeScript's link resolution when determining where @link tags point. This only applies to JSDoc style comments";
     readonly help_preserveLinkText: "If set, @link tags without link text will use the text content as the link. If not set, will use the target reflection name";
@@ -230,6 +232,7 @@ declare const _default: {
     readonly help_treatValidationWarningsAsErrors: "If set, warnings emitted during validation will be treated as errors. This option cannot be used to disable treatWarningsAsErrors for validation warnings";
     readonly help_intentionallyNotExported: "A list of types which should not produce 'referenced but not documented' warnings";
     readonly help_requiredToBeDocumented: "A list of reflection kinds that must be documented";
+    readonly help_intentionallyNotDocumented: "A list of full reflection names which should not produce warnings about not being documented";
     readonly help_validation: "Specify which validation steps TypeDoc should perform on your generated documentation";
     readonly unknown_option_0_you_may_have_meant_1: "Unknown option '{0}' You may have meant:\n\t{1}";
     readonly option_0_must_be_between_1_and_2: "{0} must be between {1} and {2}";
@@ -246,7 +249,7 @@ declare const _default: {
     readonly highlightLanguages_contains_invalid_languages_0: "highlightLanguages contains invalid languages: {0}, run typedoc --help for a list of supported languages";
     readonly hostedBaseUrl_must_start_with_http: "hostedBaseUrl must start with http:// or https://";
     readonly useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set";
-    readonly favicon_must_have_one_of_the_following_extensions_0: "Favicon must have on of the following extensions: {0}";
+    readonly favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}";
     readonly option_0_must_be_an_object: "The '{0}' option must be a non-array object";
     readonly option_0_must_be_a_function: "The '{0}' option must be a function";
     readonly option_0_must_be_object_with_urls: "{0} must be an object with string labels as keys and URL values";

package/dist/lib/output/formatter.js

@@ -332,7 +332,12 @@ const typeBuilder = {
             }
         }
         else if (type.externalUrl) {
-            name = simpleElement(JSX.createElement("a", { href: type.externalUrl, class: "tsd-signature-type external", target: "_blank" }, type.name));
+            if (type.externalUrl === "#") {
+                name = simpleElement(JSX.createElement("span", { class: "tsd-signature-type external" }, type.name));
+            }
+            else {
+                name = simpleElement(JSX.createElement("a", { href: type.externalUrl, class: "tsd-signature-type external", target: "_blank" }, type.name));
+            }
         }
         else if (type.refersToTypeParameter) {
             name = simpleElement(JSX.createElement("span", { class: "tsd-signature-type tsd-kind-type-parameter" }, type.name));

package/dist/lib/output/plugins/AssetsPlugin.js

@@ -102,7 +102,8 @@ let AssetsPlugin = (() => {
         }
         onRenderBegin(event) {
             const dest = join(event.outputDirectory, "assets");
-            if ([".ico", ".png", ".svg"].includes(extname(this.favicon))) {
+            if (!/^https?:\/\//i.test(this.favicon) &&
+                [".ico", ".png", ".svg"].includes(extname(this.favicon))) {
                 copySync(this.favicon, join(dest, "favicon" + extname(this.favicon)));
             }
             if (this.customCss) {

package/dist/lib/output/themes/MarkedPlugin.js

@@ -190,11 +190,13 @@ let MarkedPlugin = (() => {
                                     }
                                     if (useHtml) {
                                         const text = part.tag === "@linkcode" ? `<code>${part.text}</code>` : part.text;
-                                        result.push(`<a href="${url}"${kindClass ? ` class="${kindClass}"` : ""}>${text}</a>`);
+                                        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(`[${text}](${url})`);
+                                        result.push(url ? `[${text}](${url})` : text);
                                     }
                                 }
                                 else {
@@ -323,7 +325,7 @@ let MarkedPlugin = (() => {
                     // the introduction of support for customized routers whenever
                     // that becomes a real thing.
                     if (this.markdownLinkExternal &&
-                        /https?:\/\//i.test(href) &&
+                        /^https?:\/\//i.test(href) &&
                         !(href + "/").startsWith(this.hostedBaseUrl)) {
                         token.attrSet("target", "_blank");
                         const classes = token.attrGet("class")?.split(" ") || [];

package/dist/lib/output/themes/default/layouts/default.js

@@ -5,6 +5,9 @@ function favicon(context) {
     const fav = context.options.getValue("favicon");
     if (!fav)
         return null;
+    if (/^https?:\/\//i.test(fav)) {
+        return JSX.createElement("link", { rel: "icon", href: fav });
+    }
     switch (extname(fav)) {
         case ".ico":
             return JSX.createElement("link", { rel: "icon", href: context.relativeURL("assets/favicon.ico", true) });

package/dist/lib/utils/options/declaration.d.ts

@@ -198,6 +198,7 @@ export interface TypeDocOptionMap {
     intentionallyNotExported: string[];
     validation: ValidationOptions;
     requiredToBeDocumented: ReflectionKind.KindString[];
+    intentionallyNotDocumented: string[];
     watch: boolean;
     preserveWatchOutput: boolean;
     help: boolean;
@@ -276,31 +277,35 @@ export declare enum ParameterType {
      * Resolved according to the config directory.
      */
     Path = 1,
-    Number = 2,
-    Boolean = 3,
-    Map = 4,
-    Mixed = 5,
-    Array = 6,
+    /**
+     * Resolved according to the config directory unless it starts with https?://
+     */
+    UrlOrPath = 2,
+    Number = 3,
+    Boolean = 4,
+    Map = 5,
+    Mixed = 6,
+    Array = 7,
     /**
      * Resolved according to the config directory.
      */
-    PathArray = 7,
+    PathArray = 8,
     /**
      * Resolved according to the config directory if it starts with `.`
      */
-    ModuleArray = 8,
+    ModuleArray = 9,
     /**
      * Resolved according to the config directory unless it starts with `**`, after skipping any leading `!` and `#` characters.
      */
-    GlobArray = 9,
+    GlobArray = 10,
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    Object = 10,
+    Object = 11,
     /**
      * An object with true/false flags
      */
-    Flags = 11
+    Flags = 12
 }
 export interface DeclarationOptionBase {
     /**
@@ -331,9 +336,9 @@ export interface StringDeclarationOption extends DeclarationOptionBase {
      * Specifies the resolution strategy. If `Path` is provided, values will be resolved according to their
      * location in a file. If `String` or no value is provided, values will not be resolved.
      */
-    type?: ParameterType.String | ParameterType.Path;
+    type?: ParameterType.String | ParameterType.Path | ParameterType.UrlOrPath;
     /**
-     * If not specified defaults to the empty string for both `String` and `Path`.
+     * If not specified defaults to the empty string for all types.
      */
     defaultValue?: string;
     /**
@@ -443,6 +448,7 @@ export type DeclarationOption = StringDeclarationOption | NumberDeclarationOptio
 export interface ParameterTypeToOptionTypeMap {
     [ParameterType.String]: string;
     [ParameterType.Path]: string;
+    [ParameterType.UrlOrPath]: string;
     [ParameterType.Number]: number;
     [ParameterType.Boolean]: boolean;
     [ParameterType.Mixed]: unknown;

package/dist/lib/utils/options/declaration.js

@@ -27,31 +27,35 @@ export var ParameterType;
      * Resolved according to the config directory.
      */
     ParameterType[ParameterType["Path"] = 1] = "Path";
-    ParameterType[ParameterType["Number"] = 2] = "Number";
-    ParameterType[ParameterType["Boolean"] = 3] = "Boolean";
-    ParameterType[ParameterType["Map"] = 4] = "Map";
-    ParameterType[ParameterType["Mixed"] = 5] = "Mixed";
-    ParameterType[ParameterType["Array"] = 6] = "Array";
+    /**
+     * Resolved according to the config directory unless it starts with https?://
+     */
+    ParameterType[ParameterType["UrlOrPath"] = 2] = "UrlOrPath";
+    ParameterType[ParameterType["Number"] = 3] = "Number";
+    ParameterType[ParameterType["Boolean"] = 4] = "Boolean";
+    ParameterType[ParameterType["Map"] = 5] = "Map";
+    ParameterType[ParameterType["Mixed"] = 6] = "Mixed";
+    ParameterType[ParameterType["Array"] = 7] = "Array";
     /**
      * Resolved according to the config directory.
      */
-    ParameterType[ParameterType["PathArray"] = 7] = "PathArray";
+    ParameterType[ParameterType["PathArray"] = 8] = "PathArray";
     /**
      * Resolved according to the config directory if it starts with `.`
      */
-    ParameterType[ParameterType["ModuleArray"] = 8] = "ModuleArray";
+    ParameterType[ParameterType["ModuleArray"] = 9] = "ModuleArray";
     /**
      * Resolved according to the config directory unless it starts with `**`, after skipping any leading `!` and `#` characters.
      */
-    ParameterType[ParameterType["GlobArray"] = 9] = "GlobArray";
+    ParameterType[ParameterType["GlobArray"] = 10] = "GlobArray";
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    ParameterType[ParameterType["Object"] = 10] = "Object";
+    ParameterType[ParameterType["Object"] = 11] = "Object";
     /**
      * An object with true/false flags
      */
-    ParameterType[ParameterType["Flags"] = 11] = "Flags";
+    ParameterType[ParameterType["Flags"] = 12] = "Flags";
 })(ParameterType || (ParameterType = {}));
 const converters = {
     [ParameterType.String](value, option, i18n) {
@@ -67,6 +71,17 @@ const converters = {
         option.validate?.(stringValue, i18n);
         return stringValue;
     },
+    [ParameterType.UrlOrPath](value, option, i18n, configPath) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        const stringValue = value == null ? "" : String(value);
+        if (/^https?:\/\//i.test(stringValue)) {
+            option.validate?.(stringValue, i18n);
+            return stringValue;
+        }
+        const resolved = resolve(configPath, stringValue);
+        option.validate?.(resolved, i18n);
+        return resolved;
+    },
     [ParameterType.Number](value, option, i18n) {
         const numValue = parseInt(String(value), 10) || 0;
         if (!valueIsWithinBounds(numValue, option.minValue, option.maxValue)) {
@@ -206,6 +221,18 @@ const defaultGetters = {
             ? defaultStr
             : join(process.cwd(), defaultStr);
     },
+    [ParameterType.UrlOrPath](option) {
+        const defaultStr = option.defaultValue ?? "";
+        if (defaultStr == "") {
+            return "";
+        }
+        if (/^https?:\/\//i.test(defaultStr)) {
+            return defaultStr;
+        }
+        return isAbsolute(defaultStr)
+            ? defaultStr
+            : join(process.cwd(), defaultStr);
+    },
     [ParameterType.Number](option) {
         return option.defaultValue ?? 0;
     },

package/dist/lib/utils/options/sources/typedoc.js

@@ -411,11 +411,12 @@ export function addTypeDocOptions(options) {
         help: (i18n) => i18n.help_favicon(),
         validate(value, i18n) {
             const allowedExtension = [".ico", ".png", ".svg"];
-            if (!allowedExtension.includes(extname(value))) {
+            if (!/^https?:\/\//i.test(value) &&
+                !allowedExtension.includes(extname(value))) {
                 throw new Error(i18n.favicon_must_have_one_of_the_following_extensions_0(allowedExtension.join(", ")));
             }
         },
-        type: ParameterType.Path,
+        type: ParameterType.UrlOrPath,
     });
     options.addDeclaration({
         name: "sourceLinkExternal",
@@ -438,7 +439,7 @@ export function addTypeDocOptions(options) {
         name: "hostedBaseUrl",
         help: (i18n) => i18n.help_hostedBaseUrl(),
         validate(value, i18n) {
-            if (!/https?:\/\//i.test(value)) {
+            if (!/^https?:\/\//i.test(value)) {
                 throw new Error(i18n.hostedBaseUrl_must_start_with_http());
             }
         },
@@ -634,7 +635,7 @@ export function addTypeDocOptions(options) {
     });
     options.addDeclaration({
         name: "suppressCommentWarningsInDeclarationFiles",
-        help: (i18n) => i18n.help_lang(),
+        help: (i18n) => i18n.help_suppressCommentWarningsInDeclarationFiles(),
         type: ParameterType.Boolean,
         defaultValue: true,
     });
@@ -839,6 +840,12 @@ export function addTypeDocOptions(options) {
         },
         defaultValue: OptionDefaults.requiredToBeDocumented,
     });
+    options.addDeclaration({
+        name: "intentionallyNotDocumented",
+        help: (i18n) => i18n.help_intentionallyNotDocumented(),
+        type: ParameterType.Array,
+        defaultValue: [],
+    });
     options.addDeclaration({
         name: "validation",
         help: (i18n) => i18n.help_validation(),

package/dist/lib/validation/documentation.d.ts

@@ -1,3 +1,3 @@
 import { type ProjectReflection, ReflectionKind } from "../models/index.js";
 import type { Logger } from "../utils/index.js";
-export declare function validateDocumentation(project: ProjectReflection, logger: Logger, requiredToBeDocumented: readonly ReflectionKind.KindString[]): void;
+export declare function validateDocumentation(project: ProjectReflection, logger: Logger, requiredToBeDocumented: readonly ReflectionKind.KindString[], intentionallyNotDocumented: readonly string[]): void;

package/dist/lib/validation/documentation.js

@@ -1,7 +1,7 @@
 import { DeclarationReflection, ReflectionKind, ReflectionType, } from "../models/index.js";
 import { removeFlag } from "../utils/enum.js";
 import { nicePath } from "../utils/paths.js";
-export function validateDocumentation(project, logger, requiredToBeDocumented) {
+export function validateDocumentation(project, logger, requiredToBeDocumented, intentionallyNotDocumented) {
     let kinds = requiredToBeDocumented.reduce((prev, cur) => prev | ReflectionKind[cur], 0);
     // Functions, Constructors, and Accessors never have comments directly on them.
     // If they are required to be documented, what's really required is that their
@@ -20,6 +20,7 @@ export function validateDocumentation(project, logger, requiredToBeDocumented) {
     }
     const toProcess = project.getReflectionsByKind(kinds);
     const seen = new Set();
+    const intentionalUsage = new Set();
     outer: while (toProcess.length) {
         const ref = toProcess.shift();
         if (seen.has(ref))
@@ -76,7 +77,16 @@ export function validateDocumentation(project, logger, requiredToBeDocumented) {
             if (symbolId.fileName.includes("node_modules")) {
                 continue;
             }
+            const intentionalIndex = intentionallyNotDocumented.indexOf(ref.getFriendlyFullName());
+            if (intentionalIndex !== -1) {
+                intentionalUsage.add(intentionalIndex);
+                continue;
+            }
             logger.warn(logger.i18n.reflection_0_kind_1_defined_in_2_does_not_have_any_documentation(ref.getFriendlyFullName(), ReflectionKind[ref.kind], nicePath(symbolId.fileName)));
         }
     }
+    const unusedIntentional = intentionallyNotDocumented.filter((_, i) => !intentionalUsage.has(i));
+    if (unusedIntentional.length) {
+        logger.warn(logger.i18n.invalid_intentionally_not_documented_names_0(unusedIntentional.join("\n\t")));
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.27.7",
+  "version": "0.27.9",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {
@@ -33,7 +33,7 @@
     "yaml": "^2.6.1"
   },
   "peerDependencies": {
-    "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x"
+    "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x"
   },
   "devDependencies": {
     "@types/lunr": "^2.3.7",
@@ -49,7 +49,7 @@
     "puppeteer": "^23.6.1",
     "semver": "^7.6.3",
     "tsx": "^4.19.2",
-    "typescript": "5.7.2",
+    "typescript": "5.8.1-rc",
     "typescript-eslint": "^8.15.0"
   },
   "files": [