typedoc 0.28.11 → 0.28.13

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export type { Icons, NavigationElement, PageDefinition, PageHeading, RendererEve
 export { Outputs } from "./lib/output/output.js";
 export { ArgumentsReader, CommentStyle, EntryPointStrategy, normalizePath, Option, OptionDefaults, Options, PackageJsonReader, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, ValidatingFileRegistry, } from "./lib/utils/index.js";
 export type { ArrayDeclarationOption, BooleanDeclarationOption, DeclarationOption, DeclarationOptionBase, DeclarationOptionToOptionType, DocumentationEntryPoint, FancyConsoleLogger, FlagsDeclarationOption, JsDocCompatibility, KeyToDeclaration, ManuallyValidatedOption, MapDeclarationOption, MixedDeclarationOption, NumberDeclarationOption, ObjectDeclarationOption, OptionsReader, OutputSpecification, ParameterTypeToOptionTypeMap, SortStrategy, StringDeclarationOption, TypeDocOptionMap, TypeDocOptions, TypeDocOptionValues, ValidationOptions, } from "./lib/utils/index.js";
-export { type ComponentPath, ConsoleLogger, type DeclarationReference, type EnumKeys, EventDispatcher, EventHooks, type GlobString, i18n, JSX, Logger, LogLevel, type Meaning, type MeaningKeyword, type MinimalNode, MinimalSourceFile, type NormalizedPath, type NormalizedPathOrModule, type NormalizedPathOrModuleOrFunction, type SymbolReference, type TranslatedString, translateTagName, } from "#utils";
+export { type ComponentPath, ConsoleLogger, type DeclarationReference, type EnumKeys, EventDispatcher, EventHooks, type GlobString, i18n, JSX, Logger, LogLevel, type Meaning, type MeaningKeyword, type MinimalNode, MinimalSourceFile, type NormalizedPath, type NormalizedPathOrModule, type NormalizedPathOrModuleOrFunction, type SymbolReference, type TagString, type TranslatedString, translateTagName, } from "#utils";
 export { type Deserializable, Deserializer, type DeserializerComponent, JSONOutput, SerializeEvent, Serializer, type SerializerComponent, type SerializerEvents, } from "./lib/serialization/index.js";
 export * as Internationalization from "./lib/internationalization/index.js";
 export type { TranslatableStrings } from "./lib/internationalization/internationalization.js";

package/dist/lib/application.d.ts

@@ -67,6 +67,10 @@ export declare class Application extends AbstractComponent<Application, Applicat
      */
     internationalization: Internationalization;
     options: Options;
+    /**
+     * Due for deprecation in 0.29, use the reference to this on {@link ProjectReflection},
+     * this was the wrong place for this member to live.
+     */
     files: FileRegistry;
     /** @internal */
     accessor lang: string;

package/dist/lib/application.js

@@ -158,6 +158,10 @@ let Application = (() => {
          */
         internationalization = new Internationalization();
         options = new Options();
+        /**
+         * Due for deprecation in 0.29, use the reference to this on {@link ProjectReflection},
+         * this was the wrong place for this member to live.
+         */
         files = new ValidatingFileRegistry();
         #lang_accessor_storage = __runInitializers(this, _lang_initializers, void 0);
         /** @internal */
@@ -260,6 +264,9 @@ let Application = (() => {
             else {
                 this.logger.level = this.options.getValue("logLevel");
             }
+            if (this.files instanceof ValidatingFileRegistry) {
+                this.files.basePath = this.options.getValue("basePath");
+            }
             for (const [lang, locales] of Object.entries(this.options.getValue("locales"))) {
                 this.internationalization.addTranslations(lang, locales);
             }
@@ -630,7 +637,7 @@ let Application = (() => {
             for (const { dir, options } of projectsToConvert) {
                 this.logger.info(i18n.converting_project_at_0(nicePath(dir)));
                 this.options = options;
-                this.files = new ValidatingFileRegistry();
+                this.files = new ValidatingFileRegistry(options.getValue("basePath"));
                 let project = await this.convert();
                 if (project) {
                     this.validate(project);

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

@@ -4,6 +4,7 @@ import { CommentStyle } from "../../utils/options/declaration.js";
 import { nicePath } from "../../utils/paths.js";
 import { ok } from "assert";
 import { assertNever, filter, firstDefined, i18n } from "#utils";
+import { resolveAliasedSymbol } from "../utils/symbols.js";
 const variablePropertyKinds = [
     ts.SyntaxKind.PropertyDeclaration,
     ts.SyntaxKind.PropertySignature,
@@ -415,6 +416,17 @@ function declarationToCommentNodes(node, checker) {
                 });
             }
         }
+        // #3003 even more magic for handling an imported symbol which appears in a shorthand property assignment
+        const originalSymbol = sourceSymbol && resolveAliasedSymbol(sourceSymbol, checker);
+        if (originalSymbol !== sourceSymbol && originalSymbol?.valueDeclaration) {
+            const commentNode = declarationToCommentNodeIgnoringParents(originalSymbol?.valueDeclaration);
+            if (commentNode) {
+                result.push({
+                    node: commentNode,
+                    inheritedFromParentDeclaration: true,
+                });
+            }
+        }
     }
     // With overloaded functions/methods, TypeScript will use the comment on the first signature
     // declaration

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

@@ -206,6 +206,9 @@ function postProcessComment(comment, i18n, getPosition, warning) {
     if ((inlineInheritDoc.length || inheritDoc.length) && remarks.length) {
         warning(i18n.content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0(getPosition()));
     }
+    if ((inlineInheritDoc.length || inheritDoc.length) && returns.length) {
+        warning(i18n.content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0(getPosition()));
+    }
 }
 const aliasedTags = new Map([["@return", "@returns"]]);
 function blockTag(comment, lexer, config, i18n, warning, files) {

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

@@ -166,8 +166,9 @@ function checkMarkdownLink(data, reentry) {
     if (link.ok) {
         // Only make a relative-link display part if it's actually a relative link.
         // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
-        if (isRelativePath(link.str)) {
-            const { target, anchor } = files.register(sourcePath, link.str) || { target: undefined, anchor: undefined };
+        const decoded = decodeURI(link.str);
+        if (isRelativePath(decoded)) {
+            const { target, anchor } = files.register(sourcePath, decoded) || { target: undefined, anchor: undefined };
             return {
                 pos: lookahead,
                 end: link.pos,
@@ -213,8 +214,9 @@ function checkReference(data) {
                 }
                 const link = MdHelpers.parseLinkDestination(token.text, lookahead, token.text.length);
                 if (link.ok) {
-                    if (isRelativePath(link.str)) {
-                        const { target, anchor } = files.register(sourcePath, link.str) || { target: undefined, anchor: undefined };
+                    const decoded = decodeURI(link.str);
+                    if (isRelativePath(decoded)) {
+                        const { target, anchor } = files.register(sourcePath, decoded) || { target: undefined, anchor: undefined };
                         return {
                             pos: lookahead,
                             end: link.pos,
@@ -273,8 +275,9 @@ function checkAttributes(data, attributes) {
     return links;
 }
 function checkAttributeDirectPath(data, text, pos, end) {
-    if (isRelativePath(text.trim())) {
-        const { target, anchor } = data.files.register(data.sourcePath, text.trim()) || { target: undefined, anchor: undefined };
+    const decoded = decodeURI(text.trim());
+    if (isRelativePath(decoded)) {
+        const { target, anchor } = data.files.register(data.sourcePath, decoded) || { target: undefined, anchor: undefined };
         return [{
                 pos,
                 end,
@@ -302,8 +305,9 @@ function checkAttributeSrcSet(data, text, pos, _end) {
         // TypeDoc: We don't exactly match this, PR welcome! For now, just permit anything
         // that's not whitespace or a comma
         const url = text.slice(textPos).match(/^[^\t\r\f\n ,]+/);
-        if (url && isRelativePath(url[0])) {
-            const { target, anchor } = data.files.register(data.sourcePath, url[0]) || { target: undefined, anchor: undefined };
+        const decoded = url && decodeURI(url[0]);
+        if (decoded && isRelativePath(decoded)) {
+            const { target, anchor } = data.files.register(data.sourcePath, decoded) || { target: undefined, anchor: undefined };
             result.push({
                 pos: pos + textPos,
                 end: pos + textPos + url[0].length,

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

@@ -1,3 +1,4 @@
+import { type TagString } from "#utils";
 import { ConverterComponent } from "../components.js";
 import type { Converter } from "../converter.js";
 /**
@@ -56,8 +57,8 @@ import type { Converter } from "../converter.js";
  * - Resolve `@link` tags to point to target reflections
  */
 export declare class CommentPlugin extends ConverterComponent {
-    accessor excludeTags: `@${string}`[];
-    accessor cascadedModifierTags: `@${string}`[];
+    accessor excludeTags: TagString[];
+    accessor cascadedModifierTags: TagString[];
     accessor excludeInternal: boolean;
     accessor excludePrivate: boolean;
     accessor excludeProtected: boolean;

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

@@ -4,7 +4,7 @@ import { DeclarationReflection, ReflectionFlag, ReflectionKind, SignatureReflect
 import { ReferenceType, ReflectionType } from "../../models/types.js";
 import { filterMap, zip } from "#utils";
 import { ConverterComponent } from "../components.js";
-import { getHumanName } from "../../utils/index.js";
+import { findPackageForPath, getHumanName } from "../../utils/index.js";
 import { ConverterEvents } from "../converter-events.js";
 /**
  * A plugin that detects interface implementations of functions and
@@ -95,22 +95,23 @@ export class ImplementsPlugin extends ConverterComponent {
         // serialization/deserialization, might point to an unexpected location. (See the mixin
         // converter tests, I suspect this might actually be an indication of something else slightly
         // broken there, but don't want to spend more time with this right now.)
-        // #2982, even more unfortunately, we only want to keep the link if it is pointing to a reflection
-        // which will receive a link during rendering.
-        const isValidRef = (ref) => ref.reflection && !ref.reflection.parent?.kindOf(ReflectionKind.TypeLiteral);
+        // #2982/#3007, even more unfortunately, we only want to keep the link if it is pointing
+        // to a reflection which will receive a link during rendering, we pick this based on it being
+        // the type of member we expect to point to.
+        const isValidRef = (ref) => !!ref.reflection?.parent?.kindOf(ReflectionKind.ClassOrInterface | ReflectionKind.Method | ReflectionKind.Constructor);
         for (const child of reflection.children || []) {
             if (child.inheritedFrom && !isValidRef(child.inheritedFrom)) {
-                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project);
+                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project, child.inheritedFrom.package);
             }
             if (child.overwrites && !isValidRef(child.overwrites)) {
-                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project);
+                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project, child.overwrites.package);
             }
             for (const childSig of child.getAllSignatures()) {
                 if (childSig.inheritedFrom && !isValidRef(childSig.inheritedFrom)) {
-                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project);
+                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project, childSig.inheritedFrom.package);
                 }
                 if (childSig.overwrites && !isValidRef(childSig.overwrites)) {
-                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project);
+                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project, childSig.overwrites.package);
                 }
             }
         }
@@ -325,15 +326,27 @@ export class ImplementsPlugin extends ConverterComponent {
         }
     }
 }
+function getConstructorPackagePath(context, clause) {
+    const symbol = context.getSymbolAtLocation(clause.expression);
+    if (!symbol)
+        return undefined;
+    const resolvedSymbol = context.resolveAliasedSymbol(symbol);
+    const symbolPath = resolvedSymbol?.declarations?.[0]?.getSourceFile().fileName;
+    if (!symbolPath)
+        return undefined;
+    return findPackageForPath(symbolPath)?.[0];
+}
 function constructorInheritance(context, reflection, childDecl, constructorDecl) {
     const extendsClause = childDecl.heritageClauses?.find((cl) => cl.token === ts.SyntaxKind.ExtendsKeyword);
     if (!extendsClause)
         return;
-    const name = `${extendsClause.types[0].getText()}.constructor`;
+    const extendsType = extendsClause.types[0];
+    const refPackage = getConstructorPackagePath(context, extendsType);
+    const name = `${extendsType.getText()}.constructor`;
     const key = constructorDecl ? "overwrites" : "inheritedFrom";
-    reflection[key] ??= ReferenceType.createBrokenReference(name, context.project);
+    reflection[key] ??= ReferenceType.createBrokenReference(name, context.project, refPackage);
     for (const sig of reflection.signatures ?? []) {
-        sig[key] ??= ReferenceType.createBrokenReference(name, context.project);
+        sig[key] ??= ReferenceType.createBrokenReference(name, context.project, refPackage);
     }
 }
 function findProperty(reflection, parent) {
@@ -356,7 +369,7 @@ function createLink(context, reflection, clause, expr, symbol, isInherit) {
     const rootSymbols = context.checker.getRootSymbols(symbol);
     const ref = rootSymbols.length && rootSymbols[0] != symbol
         ? context.createSymbolReference(rootSymbols[0], context, name)
-        : ReferenceType.createBrokenReference(name, context.project);
+        : ReferenceType.createBrokenReference(name, context.project, undefined);
     link(reflection);
     link(reflection.getSignature);
     link(reflection.setSignature);

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

@@ -149,6 +149,8 @@ let InheritDocPlugin = (() => {
                 return;
             }
             target.comment.removeTags("@inheritDoc");
+            target.comment.removeTags("@remarks");
+            target.comment.removeTags("@returns");
             target.comment.summary = Comment.cloneDisplayParts(source.comment.summary);
             const remarks = source.comment.getTag("@remarks");
             if (remarks) {

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

@@ -1,6 +1,5 @@
 import { ConverterComponent } from "../components.js";
 import type { Converter } from "../converter.js";
-import { type NormalizedPath } from "#utils";
 /**
  * A handler that attaches source file information to reflections.
  */
@@ -10,7 +9,7 @@ export declare class SourcePlugin extends ConverterComponent {
     accessor gitRemote: string;
     accessor disableGit: boolean;
     accessor sourceLinkTemplate: string;
-    accessor basePath: NormalizedPath;
+    get displayBasePath(): import("#utils").NormalizedPath;
     /**
      * All file names to find the base path from.
      */

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

@@ -62,9 +62,6 @@ let SourcePlugin = (() => {
     let _sourceLinkTemplate_decorators;
     let _sourceLinkTemplate_initializers = [];
     let _sourceLinkTemplate_extraInitializers = [];
-    let _basePath_decorators;
-    let _basePath_initializers = [];
-    let _basePath_extraInitializers = [];
     return class SourcePlugin extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -73,13 +70,11 @@ let SourcePlugin = (() => {
             _gitRemote_decorators = [Option("gitRemote")];
             _disableGit_decorators = [Option("disableGit")];
             _sourceLinkTemplate_decorators = [Option("sourceLinkTemplate")];
-            _basePath_decorators = [Option("basePath")];
             __esDecorate(this, null, _disableSources_decorators, { kind: "accessor", name: "disableSources", static: false, private: false, access: { has: obj => "disableSources" in obj, get: obj => obj.disableSources, set: (obj, value) => { obj.disableSources = value; } }, metadata: _metadata }, _disableSources_initializers, _disableSources_extraInitializers);
             __esDecorate(this, null, _gitRevision_decorators, { kind: "accessor", name: "gitRevision", static: false, private: false, access: { has: obj => "gitRevision" in obj, get: obj => obj.gitRevision, set: (obj, value) => { obj.gitRevision = value; } }, metadata: _metadata }, _gitRevision_initializers, _gitRevision_extraInitializers);
             __esDecorate(this, null, _gitRemote_decorators, { kind: "accessor", name: "gitRemote", static: false, private: false, access: { has: obj => "gitRemote" in obj, get: obj => obj.gitRemote, set: (obj, value) => { obj.gitRemote = value; } }, metadata: _metadata }, _gitRemote_initializers, _gitRemote_extraInitializers);
             __esDecorate(this, null, _disableGit_decorators, { kind: "accessor", name: "disableGit", static: false, private: false, access: { has: obj => "disableGit" in obj, get: obj => obj.disableGit, set: (obj, value) => { obj.disableGit = value; } }, metadata: _metadata }, _disableGit_initializers, _disableGit_extraInitializers);
             __esDecorate(this, null, _sourceLinkTemplate_decorators, { kind: "accessor", name: "sourceLinkTemplate", static: false, private: false, access: { has: obj => "sourceLinkTemplate" in obj, get: obj => obj.sourceLinkTemplate, set: (obj, value) => { obj.sourceLinkTemplate = value; } }, metadata: _metadata }, _sourceLinkTemplate_initializers, _sourceLinkTemplate_extraInitializers);
-            __esDecorate(this, null, _basePath_decorators, { kind: "accessor", name: "basePath", static: false, private: false, access: { has: obj => "basePath" in obj, get: obj => obj.basePath, set: (obj, value) => { obj.basePath = value; } }, metadata: _metadata }, _basePath_initializers, _basePath_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         #disableSources_accessor_storage = __runInitializers(this, _disableSources_initializers, void 0);
@@ -97,13 +92,13 @@ let SourcePlugin = (() => {
         #sourceLinkTemplate_accessor_storage = (__runInitializers(this, _disableGit_extraInitializers), __runInitializers(this, _sourceLinkTemplate_initializers, void 0));
         get sourceLinkTemplate() { return this.#sourceLinkTemplate_accessor_storage; }
         set sourceLinkTemplate(value) { this.#sourceLinkTemplate_accessor_storage = value; }
-        #basePath_accessor_storage = (__runInitializers(this, _sourceLinkTemplate_extraInitializers), __runInitializers(this, _basePath_initializers, void 0));
-        get basePath() { return this.#basePath_accessor_storage; }
-        set basePath(value) { this.#basePath_accessor_storage = value; }
+        get displayBasePath() {
+            return this.application.options.getValue("displayBasePath") || this.application.options.getValue("basePath");
+        }
         /**
          * All file names to find the base path from.
          */
-        fileNames = (__runInitializers(this, _basePath_extraInitializers), new Set());
+        fileNames = (__runInitializers(this, _sourceLinkTemplate_extraInitializers), new Set());
         repositories;
         constructor(owner) {
             super(owner);
@@ -170,7 +165,7 @@ let SourcePlugin = (() => {
                 !this.gitRevision) {
                 this.application.logger.warn(i18n.disable_git_set_and_git_revision_used());
             }
-            const basePath = this.basePath || getCommonDirectory([...this.fileNames]);
+            const basePath = this.displayBasePath || getCommonDirectory([...this.fileNames]);
             this.repositories ||= new RepositoryManager(basePath, this.gitRevision, this.gitRemote, this.sourceLinkTemplate, this.disableGit, this.application.logger);
             for (const id in context.project.reflections) {
                 const refl = context.project.reflections[id];

package/dist/lib/converter/symbols.js

@@ -631,7 +631,11 @@ function convertVariableAsEnum(context, symbol, exportSymbol) {
     const reflection = context.createDeclarationReflection(ReflectionKind.Enum, symbol, exportSymbol);
     context.finalizeDeclarationReflection(reflection);
     const rc = context.withScope(reflection);
-    const declaration = symbol.declarations.find(ts.isVariableDeclaration);
+    const declaration = symbol.valueDeclaration;
+    if (!declaration) {
+        context.logger.error(i18n.converting_0_as_enum_requires_value_declaration(symbol.name), symbol.declarations?.[0]);
+        return;
+    }
     const type = context.checker.getTypeAtLocation(declaration);
     for (const prop of type.getProperties()) {
         const reflection = rc.createDeclarationReflection(ReflectionKind.EnumMember, prop, void 0);

package/dist/lib/converter/types.js

@@ -410,7 +410,7 @@ const queryConverter = {
         if (!querySymbol) {
             // This can happen if someone uses `typeof` on some property
             // on a variable typed as `any` with a name that doesn't exist.
-            return new QueryType(ReferenceType.createBrokenReference(node.exprName.getText(), context.project));
+            return new QueryType(ReferenceType.createBrokenReference(node.exprName.getText(), context.project, undefined));
         }
         const ref = context.createSymbolReference(context.resolveAliasedSymbol(querySymbol), context, node.exprName.getText());
         ref.preferValues = true;
@@ -454,7 +454,7 @@ const referenceConverter = {
         if (!symbol) {
             // This happens when we get a reference to a type parameter
             // created within a mapped type, `K` in: `{ [K in T]: string }`
-            const ref = ReferenceType.createBrokenReference(context.checker.typeToString(type), context.project);
+            const ref = ReferenceType.createBrokenReference(context.checker.typeToString(type), context.project, undefined);
             ref.refersToTypeParameter = true;
             return ref;
         }

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

@@ -31,6 +31,7 @@ module.exports = {
     converting_union_as_interface: `Using @interface on a union type will discard properties not present on all branches of the union. TypeDoc's output may not accurately describe your source code`,
     converting_0_as_class_requires_value_declaration: `Converting {0} as a class requires a declaration which represents a non-type value`,
     converting_0_as_class_without_construct_signatures: `{0} is being converted as a class, but does not have any construct signatures`,
+    converting_0_as_enum_requires_value_declaration: `Converting {0} as an enum requires a declaration which represents a non-type value`,
     comment_for_0_should_not_contain_block_or_modifier_tags: `The comment for {0} should not contain any block or modifier tags`,
     symbol_0_has_multiple_declarations_with_comment: `{0} has multiple declarations with a comment. An arbitrary comment will be used`,
     comments_for_0_are_declared_at_1: `The comments for {0} are declared at:\n\t{1}`,
@@ -44,6 +45,7 @@ module.exports = {
     at_most_one_inheritdoc_tag_expected_in_comment_at_0: "At most one @inheritDoc tag is expected in a comment, ignoring all but the first in comment at {0}",
     content_in_summary_overwritten_by_inheritdoc_in_comment_at_0: "Content in the summary section will be overwritten by the @inheritDoc tag in comment at {0}",
     content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @remarks block will be overwritten by the @inheritDoc tag in comment at {0}",
+    content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @returns block will be overwritten by the @inheritDoc tag in comment at {0}",
     example_tag_literal_name: "The first line of an example tag will be taken literally as the example name, and should only contain text",
     inheritdoc_tag_properly_capitalized: "The @inheritDoc tag should be properly capitalized",
     treating_unrecognized_tag_0_as_modifier: `Treating unrecognized tag {0} as a modifier tag`,
@@ -194,11 +196,12 @@ module.exports = {
     help_gitRevision: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files. Has no effect if disableSources is set",
     help_gitRemote: "Use the specified remote for linking to GitHub/Bitbucket source files. Has no effect if disableGit or disableSources is set",
     help_disableGit: "Assume that all can be linked to with the sourceLinkTemplate, sourceLinkTemplate must be set if this is enabled. {path} will be rooted at basePath",
-    help_basePath: "Specifies the base path to be used when displaying file paths",
+    help_displayBasePath: "Specifies the base path to be used when displaying file paths. If not specified, basePath is used.",
     help_excludeTags: "Remove the listed block/modifier tags from doc comments",
     help_notRenderedTags: "Tags which will be preserved in doc comments, but not rendered when creating output",
     help_cascadedModifierTags: "Modifier tags which should be copied to all children of the parent reflection",
     help_readme: "Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page and start the documentation on the globals page",
+    help_basePath: "Specifies a path which links may be resolved relative to.",
     help_cname: "Set the CNAME file text, it's useful for custom domains on GitHub Pages",
     help_favicon: "Path to favicon to include as the site icon",
     help_sourceLinkExternal: "Specifies that source links should be treated as external links to be opened in a new tab",

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

@@ -28,6 +28,7 @@ declare const _default: {
     readonly converting_union_as_interface: "Using @interface on a union type will discard properties not present on all branches of the union. TypeDoc's output may not accurately describe your source code";
     readonly converting_0_as_class_requires_value_declaration: "Converting {0} as a class requires a declaration which represents a non-type value";
     readonly converting_0_as_class_without_construct_signatures: "{0} is being converted as a class, but does not have any construct signatures";
+    readonly converting_0_as_enum_requires_value_declaration: "Converting {0} as an enum requires a declaration which represents a non-type value";
     readonly comment_for_0_should_not_contain_block_or_modifier_tags: "The comment for {0} should not contain any block or modifier tags";
     readonly symbol_0_has_multiple_declarations_with_comment: "{0} has multiple declarations with a comment. An arbitrary comment will be used";
     readonly comments_for_0_are_declared_at_1: "The comments for {0} are declared at:\n\t{1}";
@@ -40,6 +41,7 @@ declare const _default: {
     readonly at_most_one_inheritdoc_tag_expected_in_comment_at_0: "At most one @inheritDoc tag is expected in a comment, ignoring all but the first in comment at {0}";
     readonly content_in_summary_overwritten_by_inheritdoc_in_comment_at_0: "Content in the summary section will be overwritten by the @inheritDoc tag in comment at {0}";
     readonly content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @remarks block will be overwritten by the @inheritDoc tag in comment at {0}";
+    readonly content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0: "Content in the @returns block will be overwritten by the @inheritDoc tag in comment at {0}";
     readonly example_tag_literal_name: "The first line of an example tag will be taken literally as the example name, and should only contain text";
     readonly inheritdoc_tag_properly_capitalized: "The @inheritDoc tag should be properly capitalized";
     readonly treating_unrecognized_tag_0_as_modifier: "Treating unrecognized tag {0} as a modifier tag";
@@ -181,11 +183,12 @@ declare const _default: {
     readonly help_gitRevision: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files. Has no effect if disableSources is set";
     readonly help_gitRemote: "Use the specified remote for linking to GitHub/Bitbucket source files. Has no effect if disableGit or disableSources is set";
     readonly help_disableGit: "Assume that all can be linked to with the sourceLinkTemplate, sourceLinkTemplate must be set if this is enabled. {path} will be rooted at basePath";
-    readonly help_basePath: "Specifies the base path to be used when displaying file paths";
+    readonly help_displayBasePath: "Specifies the base path to be used when displaying file paths. If not specified, basePath is used.";
     readonly help_excludeTags: "Remove the listed block/modifier tags from doc comments";
     readonly help_notRenderedTags: "Tags which will be preserved in doc comments, but not rendered when creating output";
     readonly help_cascadedModifierTags: "Modifier tags which should be copied to all children of the parent reflection";
     readonly help_readme: "Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page and start the documentation on the globals page";
+    readonly help_basePath: "Specifies a path which links may be resolved relative to.";
     readonly help_cname: "Set the CNAME file text, it's useful for custom domains on GitHub Pages";
     readonly help_favicon: "Path to favicon to include as the site icon";
     readonly help_sourceLinkExternal: "Specifies that source links should be treated as external links to be opened in a new tab";

package/dist/lib/models/Comment.d.ts

@@ -1,4 +1,4 @@
-import { type NormalizedPath } from "#utils";
+import { type NormalizedPath, type TagString } from "#utils";
 import type { Reflection } from "./Reflection.js";
 import { ReflectionSymbolId } from "./ReflectionSymbolId.js";
 import type { Deserializer, JSONOutput, Serializer } from "#serialization";
@@ -36,7 +36,7 @@ export type CommentDisplayPart =
  */
 export interface InlineTagDisplayPart {
     kind: "inline-tag";
-    tag: `@${string}`;
+    tag: TagString;
     text: string;
     target?: Reflection | string | ReflectionSymbolId;
     tsLinkText?: string;
@@ -79,7 +79,7 @@ export declare class CommentTag {
     /**
      * The name of this tag, e.g. `@returns`, `@example`
      */
-    tag: `@${string}`;
+    tag: TagString;
     /**
      * Some tags, (`@typedef`, `@param`, `@property`, etc.) may have a user defined identifier associated with them.
      * If this tag is one of those, it will be parsed out and included here.
@@ -98,7 +98,7 @@ export declare class CommentTag {
     /**
      * Create a new CommentTag instance.
      */
-    constructor(tag: `@${string}`, text: CommentDisplayPart[]);
+    constructor(tag: TagString, text: CommentDisplayPart[]);
     /**
      * Checks if this block tag is roughly equal to the other tag.
      * This isn't exactly equal, but just "roughly equal" by the tag
@@ -150,7 +150,7 @@ export declare class Comment {
     /**
      * All modifier tags present on the comment, e.g. `@alpha`, `@beta`.
      */
-    modifierTags: Set<`@${string}`>;
+    modifierTags: Set<TagString>;
     /**
      * Label associated with this reflection, if any (https://tsdoc.org/pages/tags/label/)
      */
@@ -179,7 +179,7 @@ export declare class Comment {
     /**
      * Creates a new Comment instance.
      */
-    constructor(summary?: CommentDisplayPart[], blockTags?: CommentTag[], modifierTags?: Set<`@${string}`>);
+    constructor(summary?: CommentDisplayPart[], blockTags?: CommentTag[], modifierTags?: Set<TagString>);
     /**
      * Gets either the `@summary` tag, or a short version of the comment summary
      * section for rendering in module/namespace pages.
@@ -201,36 +201,36 @@ export declare class Comment {
      */
     isEmpty(): boolean;
     /**
-     * Has this comment a visible component?
+     * Checks if this comment contains any visible text.
      *
-     * @returns TRUE when this comment has a visible component.
+     * @returns TRUE when this reflection has a visible comment.
      */
-    hasVisibleComponent(): boolean;
+    hasVisibleComponent(notRenderedTags?: readonly TagString[]): boolean;
     /**
      * 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: `@${string}`): boolean;
-    removeModifier(tagName: `@${string}`): void;
+    hasModifier(tagName: TagString): boolean;
+    removeModifier(tagName: TagString): void;
     /**
      * 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: `@${string}`): CommentTag | undefined;
+    getTag(tagName: TagString): CommentTag | undefined;
     /**
      * Get all tags with the given tag name.
      */
-    getTags(tagName: `@${string}`): CommentTag[];
-    getIdentifiedTag(identifier: string, tagName: `@${string}`): CommentTag | undefined;
+    getTags(tagName: TagString): CommentTag[];
+    getIdentifiedTag(identifier: string, tagName: TagString): CommentTag | undefined;
     /**
      * Removes all block tags with the given tag name from the comment.
      * @param tagName
      */
-    removeTags(tagName: `@${string}`): void;
+    removeTags(tagName: TagString): void;
     toObject(serializer: Serializer): JSONOutput.Comment;
     fromObject(de: Deserializer, obj: JSONOutput.Comment): void;
 }

package/dist/lib/models/Comment.js

@@ -441,13 +441,20 @@ let Comment = (() => {
             return !this.hasVisibleComponent() && this.modifierTags.size === 0;
         }
         /**
-         * Has this comment a visible component?
+         * Checks if this comment contains any visible text.
          *
-         * @returns TRUE when this comment has a visible component.
+         * @returns TRUE when this reflection has a visible comment.
          */
-        hasVisibleComponent() {
-            return (this.summary.some((x) => x.kind !== "text" || x.text !== "") ||
-                this.blockTags.length > 0);
+        hasVisibleComponent(notRenderedTags) {
+            if (this.summary.some((x) => x.kind !== "text" || x.text !== "")) {
+                return true;
+            }
+            if (notRenderedTags) {
+                return this.blockTags.some(tag => !notRenderedTags.includes(tag.tag));
+            }
+            else {
+                return this.blockTags.length > 0;
+            }
         }
         /**
          * Test whether this comment contains a tag with the given name.

package/dist/lib/models/DeclarationReflection.js

@@ -252,7 +252,7 @@ export class DeclarationReflection extends ContainerReflection {
                         this.project.registerSymbolId(refl, new ReflectionSymbolId(sid));
                     }
                     else {
-                        de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(id.toString()));
+                        de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(id));
                     }
                 }
             });

package/dist/lib/models/FileRegistry.js

@@ -55,7 +55,7 @@ export class FileRegistry {
     }
     resolve(id, project) {
         const reflId = this.mediaToReflection.get(id);
-        if (reflId) {
+        if (typeof reflId === "number") {
             return project.getReflectionById(reflId);
         }
         return this.mediaToPath.get(id);

package/dist/lib/models/ProjectReflection.js

@@ -342,7 +342,7 @@ let ProjectReflection = (() => {
             this.removedSymbolIds.delete(id);
             this.reflectionIdToSymbolIdMap.set(reflection.id, id);
             const previous = this.symbolToReflectionIdMap.get(id);
-            if (previous) {
+            if (typeof previous !== "undefined") {
                 if (typeof previous === "number") {
                     this.symbolToReflectionIdMap.set(id, [previous, reflection.id]);
                 }
@@ -407,7 +407,7 @@ let ProjectReflection = (() => {
                         this.registerSymbolId(refl, new ReflectionSymbolId(sid));
                     }
                     else {
-                        de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(id.toString()));
+                        de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(id));
                     }
                 }
             });

package/dist/lib/models/Reflection.d.ts

@@ -1,6 +1,6 @@
 import { Comment } from "./Comment.js";
 import type { ProjectReflection } from "./ProjectReflection.js";
-import { type NeverIfInternal, type TranslatedString } from "#utils";
+import { type NeverIfInternal, type TagString, type TranslatedString } from "#utils";
 import { ReflectionKind } from "./kind.js";
 import type { Deserializer, JSONOutput, Serializer } from "#serialization";
 import type { ReflectionVariant } from "./variant.js";
@@ -171,11 +171,11 @@ export declare abstract class Reflection {
      */
     setFlag(flag: ReflectionFlag, value?: boolean): void;
     /**
-     * Has this reflection a visible comment?
+     * Checks if this reflection has a comment which contains any visible text.
      *
      * @returns TRUE when this reflection has a visible comment.
      */
-    hasComment(): boolean;
+    hasComment(notRenderedTags?: readonly TagString[]): boolean;
     hasGetterOrSetter(): boolean;
     /**
      * Return a child by its name.

package/dist/lib/models/Reflection.js

@@ -359,12 +359,12 @@ let Reflection = (() => {
             this.flags.setFlag(flag, value);
         }
         /**
-         * Has this reflection a visible comment?
+         * Checks if this reflection has a comment which contains any visible text.
          *
          * @returns TRUE when this reflection has a visible comment.
          */
-        hasComment() {
-            return this.comment ? this.comment.hasVisibleComponent() : false;
+        hasComment(notRenderedTags) {
+            return this.comment ? this.comment.hasVisibleComponent(notRenderedTags) : false;
         }
         hasGetterOrSetter() {
             return false;

package/dist/lib/models/types.d.ts

@@ -393,7 +393,7 @@ export declare class ReferenceType extends Type {
      * later during conversion.
      * @internal
      */
-    static createBrokenReference(name: string, project: ProjectReflection): ReferenceType;
+    static createBrokenReference(name: string, project: ProjectReflection, packageName: string | undefined): ReferenceType;
     protected getTypeString(): string;
     needsParenthesis(): boolean;
     toObject(serializer: Serializer): JSONOutput.ReferenceType;