typedoc 0.28.16 → 0.28.17

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

@@ -13,6 +13,9 @@ export function resolveDeclarationReference(reflection, ref) {
     if (ref.moduleSource) {
         high = reflection.project.children?.filter((c) => c.kindOf(ReflectionKind.SomeModule) &&
             c.name === ref.moduleSource) || [];
+        if (!high.length && reflection.project.packageName === ref.moduleSource) {
+            high.push(reflection.project);
+        }
     }
     else if (ref.resolutionStart === "global") {
         high.push(reflection.project);

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

@@ -23,6 +23,8 @@ const variablePropertyKinds = [
 // Comments from @typedef and @callback tags are handled specially by
 // the JSDoc converter because we only want part of the comment when
 // getting them.
+// This also does NOT include kinds which should be checked after the
+// first kind/kinds have been checked for a comment.
 const wantedKinds = {
     [ReflectionKind.Project]: [
         ts.SyntaxKind.SourceFile,
@@ -38,24 +40,12 @@ const wantedKinds = {
         ts.SyntaxKind.BindingElement,
         ts.SyntaxKind.ExportSpecifier,
         ts.SyntaxKind.NamespaceExport,
-        // @namespace support
-        ts.SyntaxKind.VariableDeclaration,
-        ts.SyntaxKind.BindingElement,
-        ts.SyntaxKind.ExportAssignment,
-        ts.SyntaxKind.PropertyAccessExpression,
-        ts.SyntaxKind.PropertyDeclaration,
-        ts.SyntaxKind.PropertyAssignment,
-        ts.SyntaxKind.ShorthandPropertyAssignment,
     ],
     [ReflectionKind.Enum]: [
         ts.SyntaxKind.EnumDeclaration,
-        ts.SyntaxKind.VariableDeclaration,
     ],
     [ReflectionKind.EnumMember]: [
         ts.SyntaxKind.EnumMember,
-        // These here so that @enum gets comments
-        ts.SyntaxKind.PropertyAssignment,
-        ts.SyntaxKind.PropertySignature,
     ],
     [ReflectionKind.Variable]: variablePropertyKinds,
     [ReflectionKind.Function]: [
@@ -71,15 +61,9 @@ const wantedKinds = {
     [ReflectionKind.Class]: [
         ts.SyntaxKind.ClassDeclaration,
         ts.SyntaxKind.BindingElement,
-        // If marked with @class
-        ts.SyntaxKind.VariableDeclaration,
-        ts.SyntaxKind.ExportAssignment,
-        ts.SyntaxKind.FunctionDeclaration,
     ],
     [ReflectionKind.Interface]: [
         ts.SyntaxKind.InterfaceDeclaration,
-        ts.SyntaxKind.TypeAliasDeclaration,
-        ts.SyntaxKind.ClassDeclaration, // type only exports
     ],
     [ReflectionKind.Constructor]: [ts.SyntaxKind.Constructor],
     [ReflectionKind.Property]: variablePropertyKinds,
@@ -106,9 +90,6 @@ const wantedKinds = {
     [ReflectionKind.SetSignature]: [ts.SyntaxKind.SetAccessor],
     [ReflectionKind.TypeAlias]: [
         ts.SyntaxKind.TypeAliasDeclaration,
-        ts.SyntaxKind.FunctionDeclaration, // type only exports
-        // Intentionally not included to avoid comments being copied for variable/alias combos
-        // ts.SyntaxKind.VariableDeclaration,
     ],
     [ReflectionKind.Reference]: [
         ts.SyntaxKind.NamespaceExport,
@@ -117,6 +98,72 @@ const wantedKinds = {
     // Non-TS kind, will never have comments.
     [ReflectionKind.Document]: [],
 };
+// These kinds are checked after wantedKinds if wantedKinds doesn't result in
+// discovering a comment. This is a rather unfortunate tradeoff between discovering
+// comments for values in unusual circumstances (#2970) and avoiding duplicate
+// comments being discovered for declaration merging nastiness (#3064)
+const backupWantedKinds = {
+    [ReflectionKind.Project]: [],
+    [ReflectionKind.Module]: [],
+    [ReflectionKind.Namespace]: [
+        // @namespace support
+        ts.SyntaxKind.VariableDeclaration,
+        ts.SyntaxKind.BindingElement,
+        ts.SyntaxKind.ExportAssignment,
+        ts.SyntaxKind.PropertyAccessExpression,
+        ts.SyntaxKind.PropertyDeclaration,
+        ts.SyntaxKind.PropertyAssignment,
+        ts.SyntaxKind.ShorthandPropertyAssignment,
+    ],
+    [ReflectionKind.Enum]: [
+        ts.SyntaxKind.VariableDeclaration,
+    ],
+    [ReflectionKind.EnumMember]: [
+        // These here so that @enum gets comments
+        ts.SyntaxKind.PropertyAssignment,
+        ts.SyntaxKind.PropertySignature,
+    ],
+    [ReflectionKind.Variable]: [],
+    [ReflectionKind.Function]: [
+        ts.SyntaxKind.FunctionDeclaration,
+        ts.SyntaxKind.BindingElement,
+        ts.SyntaxKind.VariableDeclaration,
+        ts.SyntaxKind.ExportAssignment,
+        ts.SyntaxKind.PropertyAccessExpression,
+        ts.SyntaxKind.PropertyDeclaration,
+        ts.SyntaxKind.PropertyAssignment,
+        ts.SyntaxKind.ShorthandPropertyAssignment,
+    ],
+    [ReflectionKind.Class]: [
+        // If marked with @class
+        ts.SyntaxKind.VariableDeclaration,
+        ts.SyntaxKind.ExportAssignment,
+        ts.SyntaxKind.FunctionDeclaration,
+    ],
+    [ReflectionKind.Interface]: [
+        ts.SyntaxKind.TypeAliasDeclaration,
+        ts.SyntaxKind.ClassDeclaration, // type only exports
+    ],
+    [ReflectionKind.Constructor]: [],
+    [ReflectionKind.Property]: [],
+    [ReflectionKind.Method]: [],
+    [ReflectionKind.CallSignature]: [],
+    [ReflectionKind.IndexSignature]: [],
+    [ReflectionKind.ConstructorSignature]: [],
+    [ReflectionKind.Parameter]: [],
+    [ReflectionKind.TypeLiteral]: [],
+    [ReflectionKind.TypeParameter]: [],
+    [ReflectionKind.Accessor]: [],
+    [ReflectionKind.GetSignature]: [],
+    [ReflectionKind.SetSignature]: [],
+    [ReflectionKind.TypeAlias]: [
+        ts.SyntaxKind.FunctionDeclaration, // type only exports
+        ts.SyntaxKind.VariableDeclaration, // type only exports
+    ],
+    [ReflectionKind.Reference]: [],
+    // Non-TS kind, will never have comments.
+    [ReflectionKind.Document]: [],
+};
 export function discoverFileComments(node, commentStyle) {
     const text = node.text;
     const comments = collectCommentRanges(ts.getLeadingCommentRanges(text, node.pos));
@@ -165,10 +212,20 @@ function checkCommentDeclarations(commentNodes, reverse, commentStyle) {
     return discovered;
 }
 export function discoverComment(symbol, kind, logger, commentStyle, checker, declarationWarnings) {
+    const discovered = discoverCommentWorker(symbol, kind, logger, commentStyle, checker, declarationWarnings, wantedKinds[kind]);
+    if (discovered) {
+        return discovered;
+    }
+    return discoverCommentWorker(symbol, kind, logger, commentStyle, checker, declarationWarnings, backupWantedKinds[kind]);
+}
+function discoverCommentWorker(symbol, kind, logger, commentStyle, checker, declarationWarnings, wanted) {
+    if (wanted.length === 0) {
+        return;
+    }
     // For a module comment, we want the first one defined in the file,
     // not the last one, since that will apply to the import or declaration.
     const reverse = !symbol.declarations?.some(ts.isSourceFile);
-    const wantedDeclarations = filter(symbol.declarations, (decl) => wantedKinds[kind].includes(decl.kind));
+    const wantedDeclarations = filter(symbol.declarations, (decl) => wanted.includes(decl.kind));
     const commentNodes = wantedDeclarations.flatMap((decl) => declarationToCommentNodes(decl, checker));
     // Special behavior here!
     // Signatures and symbols have two distinct discovery methods as of TypeDoc 0.26.

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

@@ -66,6 +66,7 @@ export declare class CommentPlugin extends ConverterComponent {
     accessor excludeNotDocumented: boolean;
     accessor excludeCategories: string[];
     accessor defaultCategory: string;
+    accessor suppressCommentWarningsInDeclarationFiles: boolean;
     private _excludeKinds;
     private get excludeNotDocumentedKinds();
     constructor(owner: Converter);
@@ -123,4 +124,5 @@ export declare class CommentPlugin extends ConverterComponent {
     private isHidden;
     private excludedByCategory;
     private validateParamTags;
+    private suppressCommentWarnings;
 }

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

@@ -154,6 +154,9 @@ let CommentPlugin = (() => {
     let _defaultCategory_decorators;
     let _defaultCategory_initializers = [];
     let _defaultCategory_extraInitializers = [];
+    let _suppressCommentWarningsInDeclarationFiles_decorators;
+    let _suppressCommentWarningsInDeclarationFiles_initializers = [];
+    let _suppressCommentWarningsInDeclarationFiles_extraInitializers = [];
     return class CommentPlugin extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -166,6 +169,7 @@ let CommentPlugin = (() => {
             _excludeNotDocumented_decorators = [Option("excludeNotDocumented")];
             _excludeCategories_decorators = [Option("excludeCategories")];
             _defaultCategory_decorators = [Option("defaultCategory")];
+            _suppressCommentWarningsInDeclarationFiles_decorators = [Option("suppressCommentWarningsInDeclarationFiles")];
             __esDecorate(this, null, _excludeTags_decorators, { kind: "accessor", name: "excludeTags", static: false, private: false, access: { has: obj => "excludeTags" in obj, get: obj => obj.excludeTags, set: (obj, value) => { obj.excludeTags = value; } }, metadata: _metadata }, _excludeTags_initializers, _excludeTags_extraInitializers);
             __esDecorate(this, null, _cascadedModifierTags_decorators, { kind: "accessor", name: "cascadedModifierTags", static: false, private: false, access: { has: obj => "cascadedModifierTags" in obj, get: obj => obj.cascadedModifierTags, set: (obj, value) => { obj.cascadedModifierTags = value; } }, metadata: _metadata }, _cascadedModifierTags_initializers, _cascadedModifierTags_extraInitializers);
             __esDecorate(this, null, _excludeInternal_decorators, { kind: "accessor", name: "excludeInternal", static: false, private: false, access: { has: obj => "excludeInternal" in obj, get: obj => obj.excludeInternal, set: (obj, value) => { obj.excludeInternal = value; } }, metadata: _metadata }, _excludeInternal_initializers, _excludeInternal_extraInitializers);
@@ -175,6 +179,7 @@ let CommentPlugin = (() => {
             __esDecorate(this, null, _excludeNotDocumented_decorators, { kind: "accessor", name: "excludeNotDocumented", static: false, private: false, access: { has: obj => "excludeNotDocumented" in obj, get: obj => obj.excludeNotDocumented, set: (obj, value) => { obj.excludeNotDocumented = value; } }, metadata: _metadata }, _excludeNotDocumented_initializers, _excludeNotDocumented_extraInitializers);
             __esDecorate(this, null, _excludeCategories_decorators, { kind: "accessor", name: "excludeCategories", static: false, private: false, access: { has: obj => "excludeCategories" in obj, get: obj => obj.excludeCategories, set: (obj, value) => { obj.excludeCategories = value; } }, metadata: _metadata }, _excludeCategories_initializers, _excludeCategories_extraInitializers);
             __esDecorate(this, null, _defaultCategory_decorators, { kind: "accessor", name: "defaultCategory", static: false, private: false, access: { has: obj => "defaultCategory" in obj, get: obj => obj.defaultCategory, set: (obj, value) => { obj.defaultCategory = value; } }, metadata: _metadata }, _defaultCategory_initializers, _defaultCategory_extraInitializers);
+            __esDecorate(this, null, _suppressCommentWarningsInDeclarationFiles_decorators, { kind: "accessor", name: "suppressCommentWarningsInDeclarationFiles", static: false, private: false, access: { has: obj => "suppressCommentWarningsInDeclarationFiles" in obj, get: obj => obj.suppressCommentWarningsInDeclarationFiles, set: (obj, value) => { obj.suppressCommentWarningsInDeclarationFiles = value; } }, metadata: _metadata }, _suppressCommentWarningsInDeclarationFiles_initializers, _suppressCommentWarningsInDeclarationFiles_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         #excludeTags_accessor_storage = __runInitializers(this, _excludeTags_initializers, void 0);
@@ -204,7 +209,10 @@ let CommentPlugin = (() => {
         #defaultCategory_accessor_storage = (__runInitializers(this, _excludeCategories_extraInitializers), __runInitializers(this, _defaultCategory_initializers, void 0));
         get defaultCategory() { return this.#defaultCategory_accessor_storage; }
         set defaultCategory(value) { this.#defaultCategory_accessor_storage = value; }
-        _excludeKinds = __runInitializers(this, _defaultCategory_extraInitializers);
+        #suppressCommentWarningsInDeclarationFiles_accessor_storage = (__runInitializers(this, _defaultCategory_extraInitializers), __runInitializers(this, _suppressCommentWarningsInDeclarationFiles_initializers, void 0));
+        get suppressCommentWarningsInDeclarationFiles() { return this.#suppressCommentWarningsInDeclarationFiles_accessor_storage; }
+        set suppressCommentWarningsInDeclarationFiles(value) { this.#suppressCommentWarningsInDeclarationFiles_accessor_storage = value; }
+        _excludeKinds = __runInitializers(this, _suppressCommentWarningsInDeclarationFiles_extraInitializers);
         get excludeNotDocumentedKinds() {
             this._excludeKinds ??= this.application.options
                 .getValue("excludeNotDocumentedKinds")
@@ -407,12 +415,13 @@ let CommentPlugin = (() => {
         onResolve(context, reflection) {
             if (reflection.comment) {
                 if (reflection.comment.label &&
-                    !/[A-Z_][A-Z0-9_]/.test(reflection.comment.label)) {
+                    !/[A-Z_][A-Z0-9_]/.test(reflection.comment.label) &&
+                    !this.suppressCommentWarnings(reflection.comment)) {
                     context.logger.warn(i18n.label_0_for_1_cannot_be_referenced(reflection.comment.label, reflection.getFriendlyFullName()));
                 }
                 for (const group of MUTUALLY_EXCLUSIVE_MODIFIERS) {
                     const intersect = setIntersection(group, reflection.comment.modifierTags);
-                    if (intersect.size > 1) {
+                    if (intersect.size > 1 && !this.suppressCommentWarnings(reflection.comment)) {
                         const [a, b] = intersect;
                         context.logger.warn(i18n.modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2(a, b, reflection.getFriendlyFullName()));
                     }
@@ -637,12 +646,16 @@ let CommentPlugin = (() => {
             const paramTags = comment.blockTags.filter((tag) => tag.tag === "@param");
             removeIf(paramTags, (tag) => params.some((param) => param.name === tag.name));
             moveNestedParamTags(/* in-out */ paramTags, params, comment.sourcePath);
-            if (!comment.inheritedFromParentDeclaration) {
+            if (!comment.inheritedFromParentDeclaration && !this.suppressCommentWarnings(comment)) {
                 for (const tag of paramTags) {
                     this.application.logger.warn(i18n.signature_0_has_unused_param_with_name_1(signature.getFriendlyFullName(), tag.name ?? "(missing)"));
                 }
             }
         }
+        suppressCommentWarnings(comment) {
+            return this.suppressCommentWarningsInDeclarationFiles &&
+                /\.d\.(ts|mts|cts)$/.test(comment.sourcePath || "");
+        }
     };
 })();
 export { CommentPlugin };

package/dist/lib/converter/types.js

@@ -477,7 +477,7 @@ const referenceConverter = {
             return convertTypeInlined(context, type);
         }
         const ref = context.createSymbolReference(context.resolveAliasedSymbol(symbol), context, name);
-        if (type.flags & ts.TypeFlags.Substitution) {
+        if ((type.flags & ts.TypeFlags.Substitution) && name === "NoInfer" && ref.package === "typescript") {
             // NoInfer<T>
             ref.typeArguments = [
                 convertType(context, type.baseType),

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

@@ -15,14 +15,20 @@ export class Slugger {
         // (html disallowed in markdown)
         // # test <t>
         // both of the above should slug to test-t
-        return (value
+        const slug = value
             .trim()
             // remove unwanted chars
             .replace(/[\u2000-\u206F\u2E00-\u2E7F\\'!"#$%&()*+,./:;<=>?@[\]^`{|}~]/g, "")
             // change whitespace to dash
             .replace(/\s/g, "-")
             // combine adjacent dashes
-            .replace(/--+/, "-"));
+            .replace(/--+/, "-");
+        // #3065 unfortunately some headers might result in a desired slug which is
+        // completely empty. In that case, we still need to return *something* so that
+        // we don't end up generating an empty anchor, which is invalid according to the
+        // spec. GitHub's slugger rules don't handle this, so I've somewhat arbitrarily
+        // chosen "_" here. If GitHub ever fixes that issue, this might need to be adjusted.
+        return slug || "_";
     }
     constructor(options) {
         this.options = options;

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

@@ -41,7 +41,7 @@ export declare const rootPackageOptions: readonly ["plugin", "packageOptions", "
  * @interface
  */
 export type TypeDocOptions = {
-    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPathOrModuleOrFunction[] ? Array<string | ((app: Application) => Promise<void> | void)> : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes all TypeDoc specific options as returned by {@link Options.getValue}, this is

package/dist/lib/utils-common/path.d.ts

@@ -38,4 +38,5 @@ export declare namespace NormalizedPathUtils {
         name: string;
         ext: string;
     };
+    function isDeclarationFilePath(path: NormalizedPath): boolean;
 }

package/dist/lib/utils-common/path.js

@@ -123,4 +123,8 @@ export var NormalizedPathUtils;
         return { name: name.substring(0, lastDot), ext: name.substring(lastDot) };
     }
     NormalizedPathUtils.splitFilename = splitFilename;
+    function isDeclarationFilePath(path) {
+        return /\.d\.(ts|mts|cts)$/.test(path);
+    }
+    NormalizedPathUtils.isDeclarationFilePath = isDeclarationFilePath;
 })(NormalizedPathUtils || (NormalizedPathUtils = {}));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.28.16",
+  "version": "0.28.17",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {