typedoc 0.26.3 → 0.26.5

package/dist/index.d.ts

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

package/dist/index.js

@@ -29,7 +29,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeScript = exports.Internationalization = exports.SerializeEvent = exports.Deserializer = exports.Serializer = exports.JSONOutput = exports.normalizePath = exports.MinimalSourceFile = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.PackageJsonReader = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.CommentStyle = exports.Option = exports.ArgumentsReader = exports.IndexEvent = exports.MarkdownEvent = exports.RendererEvent = exports.PageEvent = exports.Theme = exports.UrlMapping = exports.Slugger = exports.DefaultThemeRenderContext = exports.DefaultTheme = exports.Renderer = exports.Context = exports.Converter = exports.Configuration = exports.Models = exports.resetReflectionID = exports.EventDispatcher = exports.Application = void 0;
+exports.TypeScript = exports.Internationalization = exports.SerializeEvent = exports.Deserializer = exports.Serializer = exports.JSONOutput = exports.normalizePath = exports.MinimalSourceFile = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.PackageJsonReader = exports.OptionDefaults = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.CommentStyle = exports.Option = exports.ArgumentsReader = exports.IndexEvent = exports.MarkdownEvent = exports.RendererEvent = exports.PageEvent = exports.Theme = exports.UrlMapping = exports.Slugger = exports.DefaultThemeRenderContext = exports.DefaultTheme = exports.Renderer = exports.Context = exports.Converter = exports.Configuration = exports.Models = exports.resetReflectionID = exports.EventDispatcher = exports.Application = void 0;
 var application_1 = require("./lib/application");
 Object.defineProperty(exports, "Application", { enumerable: true, get: function () { return application_1.Application; } });
 var events_1 = require("./lib/utils/events");
@@ -74,6 +74,7 @@ Object.defineProperty(exports, "JSX", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return utils_1.LogLevel; } });
 Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return utils_1.Logger; } });
 Object.defineProperty(exports, "Options", { enumerable: true, get: function () { return utils_1.Options; } });
+Object.defineProperty(exports, "OptionDefaults", { enumerable: true, get: function () { return utils_1.OptionDefaults; } });
 Object.defineProperty(exports, "PackageJsonReader", { enumerable: true, get: function () { return utils_1.PackageJsonReader; } });
 Object.defineProperty(exports, "ParameterHint", { enumerable: true, get: function () { return utils_1.ParameterHint; } });
 Object.defineProperty(exports, "ParameterType", { enumerable: true, get: function () { return utils_1.ParameterType; } });

package/dist/lib/application.js

@@ -471,7 +471,7 @@ let Application = (() => {
             out = Path.resolve(out);
             const ser = this.serializer.projectToObject(project, process.cwd());
             const space = this.options.getValue("pretty") ? "\t" : "";
-            await (0, index_2.writeFile)(out, JSON.stringify(ser, null, space));
+            await (0, index_2.writeFile)(out, JSON.stringify(ser, null, space) + "\n");
             this.logger.info(this.i18n.json_written_to_0((0, paths_1.nicePath)(out)));
             this.logger.verbose(`JSON rendering took ${Date.now() - start}ms`);
         }

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

@@ -308,6 +308,11 @@ function declarationToCommentNodeIgnoringParents(node) {
     // ts.SourceFile is a counterexample
     if (!node.parent)
         return node;
+    // function foo(x: number)
+    //              ^^^^^^^^^
+    if (node.kind === typescript_1.default.SyntaxKind.Parameter) {
+        return node;
+    }
     // const abc = 123
     //       ^^^
     if (node.parent.kind === typescript_1.default.SyntaxKind.VariableDeclarationList) {

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

@@ -140,8 +140,8 @@ function parseCommentString(tokens, config, file, logger, files) {
     }
     // Check for frontmatter
     let frontmatterData = {};
-    const firstBlock = content[0];
-    if (firstBlock.text.startsWith("---\n")) {
+    const firstBlock = content.at(0);
+    if (firstBlock?.text.startsWith("---\n")) {
         const end = firstBlock.text.indexOf("\n---\n");
         if (end !== -1) {
             const yamlText = firstBlock.text.slice("---\n".length, end);

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

@@ -565,13 +565,11 @@ let CommentPlugin = (() => {
             const isHidden = comment.hasModifier("@hidden") ||
                 comment.hasModifier("@ignore") ||
                 (comment.hasModifier("@internal") && this.excludeInternal);
-            if (isHidden &&
+            if (!isHidden &&
                 reflection.kindOf(models_1.ReflectionKind.ContainsCallSignatures)) {
                 return reflection
                     .getNonIndexSignatures()
-                    .every((sig) => {
-                    return !sig.comment || this.isHidden(sig);
-                });
+                    .every((sig) => this.isHidden(sig));
             }
             return isHidden;
         }

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

@@ -6,6 +6,7 @@ import { ConverterComponent } from "../components";
 export declare class ImplementsPlugin extends ConverterComponent {
     private resolved;
     private postponed;
+    private revivingSerialized;
     /**
      * Create a new ImplementsPlugin instance.
      */
@@ -16,6 +17,7 @@ export declare class ImplementsPlugin extends ConverterComponent {
     private analyzeImplements;
     private analyzeInheritance;
     private onResolveEnd;
+    private onRevive;
     private resolve;
     private tryResolve;
     private doResolve;
@@ -28,4 +30,14 @@ export declare class ImplementsPlugin extends ConverterComponent {
      * during the resolve step with links which actually point to the right place.
      */
     private onDeclaration;
+    /**
+     * Responsible for copying comments from "parent" reflections defined
+     * in either a base class or implemented interface to the child class.
+     */
+    private handleInheritedComments;
+    /**
+     * Copy the comment of the source reflection to the target reflection with a JSDoc style copy
+     * function. The TSDoc copy function is in the InheritDocPlugin.
+     */
+    private copyComment;
 }

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

@@ -65,6 +65,7 @@ let ImplementsPlugin = (() => {
             super(...arguments);
             this.resolved = new WeakSet();
             this.postponed = new WeakMap();
+            this.revivingSerialized = false;
         }
         /**
          * Create a new ImplementsPlugin instance.
@@ -73,13 +74,13 @@ let ImplementsPlugin = (() => {
             this.owner.on(converter_1.Converter.EVENT_RESOLVE_END, this.onResolveEnd.bind(this));
             this.owner.on(converter_1.Converter.EVENT_CREATE_DECLARATION, this.onDeclaration.bind(this), -1000);
             this.owner.on(converter_1.Converter.EVENT_CREATE_SIGNATURE, this.onSignature.bind(this), 1000);
-            this.application.on(application_events_1.ApplicationEvents.REVIVE, this.resolve.bind(this));
+            this.application.on(application_events_1.ApplicationEvents.REVIVE, this.onRevive.bind(this));
         }
         /**
          * Mark all members of the given class to be the implementation of the matching interface member.
          */
         analyzeImplements(project, classReflection, interfaceReflection) {
-            handleInheritedComments(classReflection, interfaceReflection);
+            this.handleInheritedComments(classReflection, interfaceReflection);
             if (!interfaceReflection.children) {
                 return;
             }
@@ -110,7 +111,7 @@ let ImplementsPlugin = (() => {
                         }
                     }
                 }
-                handleInheritedComments(classMember, interfaceMember);
+                this.handleInheritedComments(classMember, interfaceMember);
             });
         }
         analyzeInheritance(project, reflection) {
@@ -121,7 +122,7 @@ let ImplementsPlugin = (() => {
                     : void 0;
             });
             for (const parent of extendedTypes) {
-                handleInheritedComments(reflection, parent.reflection);
+                this.handleInheritedComments(reflection, parent.reflection);
                 for (const parentMember of parent.reflection.children ?? []) {
                     const child = findMatchingMember(parentMember, reflection);
                     if (child) {
@@ -132,7 +133,7 @@ let ImplementsPlugin = (() => {
                             childSig[key] = types_1.ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentSig, project);
                         }
                         child[key] = types_1.ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentMember, project);
-                        handleInheritedComments(child, parentMember);
+                        this.handleInheritedComments(child, parentMember);
                     }
                 }
             }
@@ -140,6 +141,11 @@ let ImplementsPlugin = (() => {
         onResolveEnd(context) {
             this.resolve(context.project);
         }
+        onRevive(project) {
+            this.revivingSerialized = true;
+            this.resolve(project);
+            this.revivingSerialized = false;
+        }
         resolve(project) {
             for (const id in project.reflections) {
                 const refl = project.reflections[id];
@@ -262,6 +268,73 @@ let ImplementsPlugin = (() => {
                 }
             }
         }
+        /**
+         * Responsible for copying comments from "parent" reflections defined
+         * in either a base class or implemented interface to the child class.
+         */
+        handleInheritedComments(child, parent) {
+            this.copyComment(child, parent);
+            if (parent.kindOf(index_1.ReflectionKind.Property) &&
+                child.kindOf(index_1.ReflectionKind.Accessor)) {
+                if (child.getSignature) {
+                    this.copyComment(child.getSignature, parent);
+                    child.getSignature.implementationOf = child.implementationOf;
+                }
+                if (child.setSignature) {
+                    this.copyComment(child.setSignature, parent);
+                    child.setSignature.implementationOf = child.implementationOf;
+                }
+            }
+            if (parent.kindOf(index_1.ReflectionKind.Accessor) &&
+                child.kindOf(index_1.ReflectionKind.Accessor)) {
+                if (parent.getSignature && child.getSignature) {
+                    this.copyComment(child.getSignature, parent.getSignature);
+                }
+                if (parent.setSignature && child.setSignature) {
+                    this.copyComment(child.setSignature, parent.setSignature);
+                }
+            }
+            if (parent.kindOf(index_1.ReflectionKind.FunctionOrMethod) &&
+                parent.signatures &&
+                child.signatures) {
+                for (const [cs, ps] of (0, array_1.zip)(child.signatures, parent.signatures)) {
+                    this.copyComment(cs, ps);
+                }
+            }
+            else if (parent.kindOf(index_1.ReflectionKind.Property) &&
+                parent.type instanceof types_1.ReflectionType &&
+                parent.type.declaration.signatures &&
+                child.signatures) {
+                for (const [cs, ps] of (0, array_1.zip)(child.signatures, parent.type.declaration.signatures)) {
+                    this.copyComment(cs, ps);
+                }
+            }
+        }
+        /**
+         * Copy the comment of the source reflection to the target reflection with a JSDoc style copy
+         * function. The TSDoc copy function is in the InheritDocPlugin.
+         */
+        copyComment(target, source) {
+            if (!shouldCopyComment(target, source, this.revivingSerialized)) {
+                return;
+            }
+            target.comment = source.comment.clone();
+            if (target instanceof index_1.DeclarationReflection &&
+                source instanceof index_1.DeclarationReflection) {
+                for (const [tt, ts] of (0, array_1.zip)(target.typeParameters || [], source.typeParameters || [])) {
+                    this.copyComment(tt, ts);
+                }
+            }
+            if (target instanceof index_1.SignatureReflection &&
+                source instanceof index_1.SignatureReflection) {
+                for (const [tt, ts] of (0, array_1.zip)(target.typeParameters || [], source.typeParameters || [])) {
+                    this.copyComment(tt, ts);
+                }
+                for (const [pt, ps] of (0, array_1.zip)(target.parameters || [], source.parameters || [])) {
+                    this.copyComment(pt, ps);
+                }
+            }
+        }
     };
     __setFunctionName(_classThis, "ImplementsPlugin");
     (() => {
@@ -305,7 +378,9 @@ function createLink(context, reflection, clause, expr, symbol, isInherit) {
         link(sig);
     }
     // Intentionally create broken links here. These will be replaced with real links during
-    // resolution if we can do so.
+    // resolution if we can do so. We create broken links rather than real links because in the
+    // case of an inherited symbol, we'll end up referencing a single symbol ID rather than one
+    // for each class.
     function link(target) {
         if (!target)
             return;
@@ -322,79 +397,23 @@ function createLink(context, reflection, clause, expr, symbol, isInherit) {
         }
     }
 }
-/**
- * Responsible for copying comments from "parent" reflections defined
- * in either a base class or implemented interface to the child class.
- */
-function handleInheritedComments(child, parent) {
-    copyComment(child, parent);
-    if (parent.kindOf(index_1.ReflectionKind.Property) &&
-        child.kindOf(index_1.ReflectionKind.Accessor)) {
-        if (child.getSignature) {
-            copyComment(child.getSignature, parent);
-            child.getSignature.implementationOf = child.implementationOf;
-        }
-        if (child.setSignature) {
-            copyComment(child.setSignature, parent);
-            child.setSignature.implementationOf = child.implementationOf;
-        }
-    }
-    if (parent.kindOf(index_1.ReflectionKind.Accessor) &&
-        child.kindOf(index_1.ReflectionKind.Accessor)) {
-        if (parent.getSignature && child.getSignature) {
-            copyComment(child.getSignature, parent.getSignature);
-        }
-        if (parent.setSignature && child.setSignature) {
-            copyComment(child.setSignature, parent.setSignature);
-        }
-    }
-    if (parent.kindOf(index_1.ReflectionKind.FunctionOrMethod) &&
-        parent.signatures &&
-        child.signatures) {
-        for (const [cs, ps] of (0, array_1.zip)(child.signatures, parent.signatures)) {
-            copyComment(cs, ps);
-        }
-    }
-    else if (parent.kindOf(index_1.ReflectionKind.Property) &&
-        parent.type instanceof types_1.ReflectionType &&
-        parent.type.declaration.signatures &&
-        child.signatures) {
-        for (const [cs, ps] of (0, array_1.zip)(child.signatures, parent.type.declaration.signatures)) {
-            copyComment(cs, ps);
-        }
+function shouldCopyComment(target, source, revivingSerialized) {
+    if (!source.comment) {
+        return false;
     }
-}
-/**
- * Copy the comment of the source reflection to the target reflection with a JSDoc style copy
- * function. The TSDoc copy function is in the InheritDocPlugin.
- */
-function copyComment(target, source) {
     if (target.comment) {
+        // If we're reviving, then the revived project might have a better comment
+        // on source, so copy it.
+        if (revivingSerialized && source.comment.similarTo(target.comment)) {
+            return true;
+        }
         // We might still want to copy, if the child has a JSDoc style inheritDoc tag.
         const tag = target.comment.getTag("@inheritDoc");
         if (!tag || tag.name) {
-            return;
-        }
-    }
-    if (!source.comment) {
-        return;
-    }
-    target.comment = source.comment.clone();
-    if (target instanceof index_1.DeclarationReflection &&
-        source instanceof index_1.DeclarationReflection) {
-        for (const [tt, ts] of (0, array_1.zip)(target.typeParameters || [], source.typeParameters || [])) {
-            copyComment(tt, ts);
-        }
-    }
-    if (target instanceof index_1.SignatureReflection &&
-        source instanceof index_1.SignatureReflection) {
-        for (const [tt, ts] of (0, array_1.zip)(target.typeParameters || [], source.typeParameters || [])) {
-            copyComment(tt, ts);
-        }
-        for (const [pt, ps] of (0, array_1.zip)(target.parameters || [], source.parameters || [])) {
-            copyComment(pt, ps);
+            return false;
         }
     }
+    return true;
 }
 function findMatchingMember(toMatch, container) {
     return container.children?.find((child) => child.name == toMatch.name &&

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

@@ -92,10 +92,12 @@ let LinkResolverPlugin = (() => {
                             type.elementSummaries = type.elementSummaries?.map((parts) => this.owner.resolveLinks(parts, reflection));
                         },
                     }));
+                    if (reflection.readme) {
+                        reflection.readme = this.owner.resolveLinks(reflection.readme, reflection);
+                    }
                 }
-                if (reflection instanceof models_1.DeclarationReflection &&
-                    reflection.readme) {
-                    reflection.readme = this.owner.resolveLinks(reflection.readme, reflection);
+                if (reflection.isDocument()) {
+                    reflection.content = this.owner.resolveLinks(reflection.content, reflection);
                 }
                 if (reflection instanceof models_1.ContainerReflection) {
                     if (reflection.groups) {

package/dist/lib/internationalization/translatable.d.ts

@@ -54,6 +54,8 @@ export declare const translatable: {
     readonly failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2: "Failed to resolve link to \"{0}\" in comment for {1}. You may have wanted \"{2}\"";
     readonly failed_to_resolve_link_to_0_in_readme_for_1: "Failed to resolve link to \"{0}\" in readme for {1}";
     readonly failed_to_resolve_link_to_0_in_readme_for_1_may_have_meant_2: "Failed to resolve link to \"{0}\" in readme for {1}. You may have wanted \"{2}\"";
+    readonly failed_to_resolve_link_to_0_in_document_1: "Failed to resolve link to \"{0}\" in document {1}";
+    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_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}";

package/dist/lib/internationalization/translatable.js

@@ -64,6 +64,8 @@ exports.translatable = {
     failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2: `Failed to resolve link to "{0}" in comment for {1}. You may have wanted "{2}"`,
     failed_to_resolve_link_to_0_in_readme_for_1: `Failed to resolve link to "{0}" in readme for {1}`,
     failed_to_resolve_link_to_0_in_readme_for_1_may_have_meant_2: `Failed to resolve link to "{0}" in readme for {1}. You may have wanted "{2}"`,
+    failed_to_resolve_link_to_0_in_document_1: `Failed to resolve link to "{0}" in document {1}`,
+    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_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}",

package/dist/lib/models/FileRegistry.js

@@ -49,6 +49,9 @@ class FileRegistry {
         const absolute = this.mediaToPath.get(id);
         if (!absolute)
             return;
+        if (this.names.has(id)) {
+            return this.names.get(id);
+        }
         const file = (0, path_1.basename)(absolute);
         if (!this.nameUsage.has(file)) {
             this.nameUsage.set(file, 1);

package/dist/lib/models/comments/comment.d.ts

@@ -93,6 +93,12 @@ export declare class CommentTag {
      * Create a new CommentTag instance.
      */
     constructor(tag: `@${string}`, 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
+     * text.
+     */
+    similarTo(other: CommentTag): boolean;
     clone(): CommentTag;
     toObject(serializer: Serializer): JSONOutput.CommentTag;
     fromObject(de: Deserializer, obj: JSONOutput.CommentTag): void;
@@ -191,6 +197,12 @@ export declare class Comment {
      * Creates a new Comment instance.
      */
     constructor(summary?: CommentDisplayPart[], blockTags?: CommentTag[], modifierTags?: Set<`@${string}`>);
+    /**
+     * Checks if this comment is roughly equal to the other comment.
+     * This isn't exactly equal, but just "roughly equal" by the comment
+     * text.
+     */
+    similarTo(other: Comment): boolean;
     /**
      * Create a deep clone of this comment.
      */

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

@@ -58,6 +58,17 @@ class CommentTag {
         this.tag = tag;
         this.content = text;
     }
+    /**
+     * Checks if this block tag is roughly equal to the other tag.
+     * This isn't exactly equal, but just "roughly equal" by the tag
+     * text.
+     */
+    similarTo(other) {
+        return (this.tag === other.tag &&
+            this.name === other.tag &&
+            Comment.combineDisplayParts(this.content) ===
+                Comment.combineDisplayParts(other.content));
+    }
     clone() {
         const tag = new CommentTag(this.tag, Comment.cloneDisplayParts(this.content));
         if (this.name) {
@@ -317,6 +328,28 @@ let Comment = (() => {
                 this.modifierTags = modifierTags;
                 extractLabelTag(this);
             }
+            /**
+             * Checks if this comment is roughly equal to the other comment.
+             * This isn't exactly equal, but just "roughly equal" by the comment
+             * text.
+             */
+            similarTo(other) {
+                if (_a.combineDisplayParts(this.summary) !==
+                    _a.combineDisplayParts(other.summary)) {
+                    return false;
+                }
+                // Ignore modifier tags, as they could cause false negatives
+                // if a cascaded modifier tag is present in one comment but not the other.
+                if (this.blockTags.length !== other.blockTags.length) {
+                    return false;
+                }
+                for (let i = 0; i < this.blockTags.length; ++i) {
+                    if (!this.blockTags[i].similarTo(other.blockTags[i])) {
+                        return false;
+                    }
+                }
+                return true;
+            }
             /**
              * Create a deep clone of this comment.
              */

package/dist/lib/output/index.d.ts

@@ -1,4 +1,4 @@
-export { PageEvent, RendererEvent, MarkdownEvent, IndexEvent } from "./events";
+export { PageEvent, RendererEvent, MarkdownEvent, IndexEvent, type PageHeading, } from "./events";
 export { UrlMapping } from "./models/UrlMapping";
 export type { RenderTemplate } from "./models/UrlMapping";
 export { Renderer, type RendererEvents } from "./renderer";

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

@@ -228,7 +228,7 @@ class DefaultTheme extends theme_1.Theme {
     }
     render(page, template) {
         const templateOutput = this.defaultLayoutTemplate(page, template);
-        return "<!DOCTYPE html>" + utils_1.JSX.renderElement(templateOutput);
+        return "<!DOCTYPE html>" + utils_1.JSX.renderElement(templateOutput) + "\n";
     }
     /**
      * If implementing a custom theme, it is recommended to override {@link buildNavigation} instead.
@@ -248,29 +248,36 @@ class DefaultTheme extends theme_1.Theme {
         const leaves = this.application.options.getValue("navigationLeaves");
         return getNavigationElements(project) || [];
         function toNavigation(element) {
+            const children = getNavigationElements(element);
             if (element instanceof models_1.ReflectionCategory || element instanceof models_1.ReflectionGroup) {
+                if (!children?.length) {
+                    return;
+                }
                 return {
                     text: element.title,
-                    children: getNavigationElements(element),
+                    children,
                 };
             }
+            if (!element.hasOwnDocument) {
+                return;
+            }
             return {
                 text: (0, lib_1.getDisplayName)(element),
                 path: element.url,
                 kind: element.kind,
                 class: (0, lib_1.classNames)({ deprecated: element.isDeprecated() }, theme.getReflectionClasses(element)),
-                children: getNavigationElements(element),
+                children: children?.length ? children : undefined,
             };
         }
         function getNavigationElements(parent) {
             if (parent instanceof models_1.ReflectionCategory) {
-                return parent.children.map(toNavigation);
+                return (0, utils_1.filterMap)(parent.children, toNavigation);
             }
             if (parent instanceof models_1.ReflectionGroup) {
                 if (shouldShowCategories(parent.owningReflection, opts) && parent.categories) {
-                    return parent.categories.map(toNavigation);
+                    return (0, utils_1.filterMap)(parent.categories, toNavigation);
                 }
-                return parent.children.map(toNavigation);
+                return (0, utils_1.filterMap)(parent.children, toNavigation);
             }
             if (leaves.includes(parent.getFullName())) {
                 return;
@@ -279,23 +286,23 @@ class DefaultTheme extends theme_1.Theme {
                 return;
             }
             if (parent.isDocument()) {
-                return parent.children?.map(toNavigation);
+                return (0, utils_1.filterMap)(parent.children, toNavigation);
             }
             if (!parent.kindOf(models_1.ReflectionKind.SomeModule | models_1.ReflectionKind.Project)) {
                 // Tricky: Non-module children don't show up in the navigation pane,
                 //   but any documents added by them should.
-                return parent.documents?.map(toNavigation);
+                return (0, utils_1.filterMap)(parent.documents, toNavigation);
             }
             if (parent.categories && shouldShowCategories(parent, opts)) {
-                return parent.categories.map(toNavigation);
+                return (0, utils_1.filterMap)(parent.categories, toNavigation);
             }
             if (parent.groups && shouldShowGroups(parent, opts)) {
-                return parent.groups.map(toNavigation);
+                return (0, utils_1.filterMap)(parent.groups, toNavigation);
             }
             if (opts.includeFolders && parent.childrenIncludingDocuments?.some((child) => child.name.includes("/"))) {
                 return deriveModuleFolders(parent.childrenIncludingDocuments);
             }
-            return parent.childrenIncludingDocuments?.map(toNavigation);
+            return (0, utils_1.filterMap)(parent.childrenIncludingDocuments, toNavigation);
         }
         function deriveModuleFolders(children) {
             const result = [];
@@ -318,12 +325,14 @@ class DefaultTheme extends theme_1.Theme {
             };
             // Note: This might end up putting a module within another module if we document
             // both foo/index.ts and foo/bar.ts.
-            for (const child of children) {
-                const parts = child.name.split("/");
-                const collection = resolveOrCreateParents(parts);
+            for (const child of children.filter((c) => c.hasOwnDocument)) {
                 const nav = toNavigation(child);
-                nav.text = parts[parts.length - 1];
-                collection.push(nav);
+                if (nav) {
+                    const parts = child.name.split("/");
+                    const collection = resolveOrCreateParents(parts);
+                    nav.text = parts[parts.length - 1];
+                    collection.push(nav);
+                }
             }
             // Now merge single-possible-paths together so we don't have folders in our navigation
             // which contain only another single folder.

package/dist/lib/output/themes/default/partials/member.reference.d.ts

@@ -1,4 +1,4 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import { JSX } from "../../../../utils";
 import type { ReferenceReflection } from "../../../../models";
-export declare const memberReference: ({ urlTo, i18n }: DefaultThemeRenderContext, props: ReferenceReflection) => JSX.Element;
+export declare const memberReference: ({ urlTo, i18n, commentSummary, commentTags }: DefaultThemeRenderContext, props: ReferenceReflection) => JSX.Element;

package/dist/lib/output/themes/default/partials/member.reference.js

@@ -2,23 +2,29 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memberReference = void 0;
 const utils_1 = require("../../../../utils");
-const memberReference = ({ urlTo, i18n }, props) => {
+const memberReference = ({ urlTo, i18n, commentSummary, commentTags }, props) => {
     const referenced = props.tryGetTargetReflectionDeep();
     if (!referenced) {
         return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
             i18n.theme_re_exports(),
             " ",
-            props.name));
+            props.name,
+            commentSummary(props),
+            commentTags(props)));
     }
     if (props.name === referenced.name) {
         return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
             i18n.theme_re_exports(),
             " ",
-            utils_1.JSX.createElement("a", { href: urlTo(referenced) }, referenced.name)));
+            utils_1.JSX.createElement("a", { href: urlTo(referenced) }, referenced.name),
+            commentSummary(props),
+            commentTags(props)));
     }
     return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
         i18n.theme_renames_and_re_exports(),
         " ",
-        utils_1.JSX.createElement("a", { href: urlTo(referenced) }, referenced.name)));
+        utils_1.JSX.createElement("a", { href: urlTo(referenced) }, referenced.name),
+        commentSummary(props),
+        commentTags(props)));
 };
 exports.memberReference = memberReference;

package/dist/lib/utils/array.d.ts

@@ -1,7 +1,7 @@
 export declare const emptyArray: readonly [];
 /**
  * Inserts an item into an array sorted by priority. If two items have the same priority,
- * the item will be inserted later will be placed earlier in the array.
+ * the item will be inserted later will be placed later in the array.
  * @param arr modified by inserting item.
  * @param item
  */
@@ -48,6 +48,6 @@ export declare function partition<T>(iter: Iterable<T>, predicate: (item: T) =>
 export declare function zip<T extends Iterable<any>[]>(...args: T): Iterable<{
     [K in keyof T]: T[K] extends Iterable<infer U> ? U : T[K];
 }>;
-export declare function filterMap<T, U>(iter: Iterable<T>, fn: (item: T) => U | undefined): U[];
+export declare function filterMap<T, U>(iter: Iterable<T> | undefined, fn: (item: T) => U | undefined): U[];
 export declare function firstDefined<T, U>(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined;
 export declare function filter<T>(array: readonly T[] | undefined, predicate: (value: T, index: number, array: readonly T[]) => boolean): readonly T[];