typedoc 0.25.3 → 0.25.5

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

@@ -9,20 +9,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseDeclarationReference = exports.parseMeaning = exports.parseComponentPath = exports.parseComponent = exports.parseSymbolReference = exports.parseModuleSource = exports.parseString = exports.MeaningKeywords = void 0;
 exports.MeaningKeywords = [
-    "class",
-    "interface",
-    "type",
-    "enum",
-    "namespace",
-    "function",
-    "var",
-    "constructor",
-    "member",
-    "event",
-    "call",
-    "new",
-    "index",
-    "complex",
+    "class", // SymbolFlags.Class
+    "interface", // SymbolFlags.Interface
+    "type", // SymbolFlags.TypeAlias
+    "enum", // SymbolFlags.Enum
+    "namespace", // SymbolFlags.Module
+    "function", // SymbolFlags.Function
+    "var", // SymbolFlags.Variable
+    "constructor", // SymbolFlags.Constructor
+    "member", // SymbolFlags.ClassMember | SymbolFlags.EnumMember
+    "event", //
+    "call", // SymbolFlags.Signature (for __call)
+    "new", // SymbolFlags.Signature (for __new)
+    "index", // SymbolFlags.Signature (for __index)
+    "complex", // Any complex type
     // TypeDoc specific
     "getter",
     "setter",

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

@@ -121,13 +121,15 @@ function discoverComment(symbol, kind, logger, commentStyle) {
     // not the last one, since that will apply to the import or declaration.
     const reverse = !symbol.declarations?.some(typescript_1.default.isSourceFile);
     const discovered = [];
+    const seen = new Set();
     for (const decl of symbol.declarations || []) {
         const text = decl.getSourceFile().text;
         if (wantedKinds[kind].includes(decl.kind)) {
             const node = declarationToCommentNode(decl);
-            if (!node) {
+            if (!node || seen.has(node)) {
                 continue;
             }
+            seen.add(node);
             // Special behavior here! We temporarily put the implementation comment
             // on the reflection which contains all the signatures. This lets us pull
             // the comment on the implementation if some signature does not have a comment.
@@ -292,7 +294,7 @@ function declarationToCommentNode(node) {
     if (node.kind === typescript_1.default.SyntaxKind.ExportSpecifier) {
         return node.parent.parent;
     }
-    if ([typescript_1.default.SyntaxKind.NamespaceExport, typescript_1.default.SyntaxKind.FunctionType].includes(node.kind)) {
+    if (typescript_1.default.SyntaxKind.NamespaceExport === node.kind) {
         return node.parent;
     }
     return node;

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

@@ -126,8 +126,8 @@ function blockTag(comment, lexer, config, warning) {
     (0, assert_1.ok)(blockTag.kind === lexer_1.TokenSyntaxKind.Tag, "blockTag called not at the start of a block tag."); // blockContent is broken if this fails.
     const tagName = aliasedTags.get(blockTag.text) || blockTag.text;
     let content;
-    if (tagName === "@example" && config.jsDocCompatibility.exampleTag) {
-        content = exampleBlockContent(comment, lexer, config, warning);
+    if (tagName === "@example") {
+        return exampleBlock(comment, lexer, config, warning);
     }
     else if (["@default", "@defaultValue"].includes(tagName) &&
         config.jsDocCompatibility.defaultTag) {
@@ -168,14 +168,59 @@ function defaultBlockContent(comment, lexer, config, warning) {
 /**
  * The `@example` tag gets a special case because otherwise we will produce many warnings
  * about unescaped/mismatched/missing braces in legacy JSDoc comments.
+ *
+ * In TSDoc, we also want to treat the first line of the block as the example name.
  */
-function exampleBlockContent(comment, lexer, config, warning) {
+function exampleBlock(comment, lexer, config, warning) {
     lexer.mark();
     const content = blockContent(comment, lexer, config, () => { });
     const end = lexer.done() || lexer.peek();
     lexer.release();
-    if (content.some((part) => part.kind === "code" && part.text.startsWith("```"))) {
-        return blockContent(comment, lexer, config, warning);
+    if (!config.jsDocCompatibility.exampleTag ||
+        content.some((part) => part.kind === "code" && part.text.startsWith("```"))) {
+        let exampleName = "";
+        // First line of @example block is the example name.
+        let warnedAboutRichNameContent = false;
+        outer: while ((lexer.done() || lexer.peek()) !== end) {
+            const next = lexer.peek();
+            switch (next.kind) {
+                case lexer_1.TokenSyntaxKind.NewLine:
+                    lexer.take();
+                    break outer;
+                case lexer_1.TokenSyntaxKind.Text: {
+                    const newline = next.text.indexOf("\n");
+                    if (newline !== -1) {
+                        exampleName += next.text.substring(0, newline);
+                        next.pos += newline + 1;
+                        break outer;
+                    }
+                    else {
+                        exampleName += lexer.take().text;
+                    }
+                    break;
+                }
+                case lexer_1.TokenSyntaxKind.Code:
+                case lexer_1.TokenSyntaxKind.Tag:
+                case lexer_1.TokenSyntaxKind.TypeAnnotation:
+                case lexer_1.TokenSyntaxKind.CloseBrace:
+                case lexer_1.TokenSyntaxKind.OpenBrace:
+                    if (!warnedAboutRichNameContent) {
+                        warning("The first line of an example tag will be taken literally as" +
+                            " the example name, and should only contain text.", lexer.peek());
+                        warnedAboutRichNameContent = true;
+                    }
+                    exampleName += lexer.take().text;
+                    break;
+                default:
+                    (0, utils_1.assertNever)(next.kind);
+            }
+        }
+        const content = blockContent(comment, lexer, config, warning);
+        const tag = new models_1.CommentTag("@example", content);
+        if (exampleName.trim()) {
+            tag.name = exampleName.trim();
+        }
+        return tag;
     }
     const tokens = [];
     while ((lexer.done() || lexer.peek()) !== end) {
@@ -187,24 +232,22 @@ function exampleBlockContent(comment, lexer, config, warning) {
         .trim();
     const caption = blockText.match(/^\s*<caption>(.*?)<\/caption>\s*(\n|$)/);
     if (caption) {
-        return [
-            {
-                kind: "text",
-                text: caption[1] + "\n",
-            },
+        const tag = new models_1.CommentTag("@example", [
             {
                 kind: "code",
                 text: makeCodeBlock(blockText.slice(caption[0].length)),
             },
-        ];
+        ]);
+        tag.name = caption[1];
+        return tag;
     }
     else {
-        return [
+        return new models_1.CommentTag("@example", [
             {
                 kind: "code",
                 text: makeCodeBlock(blockText),
             },
-        ];
+        ]);
     }
 }
 function blockContent(comment, lexer, config, warning) {

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

@@ -82,8 +82,5 @@ export declare class Context {
     getFileComment(node: ts.SourceFile): import("../models/index").Comment | undefined;
     getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag): import("../models/index").Comment | undefined;
     getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): import("../models/index").Comment | undefined;
-    /**
-     * @param callback  The callback function that should be executed with the changed context.
-     */
     withScope(scope: Reflection): Context;
 }

package/dist/lib/converter/context.js

@@ -184,9 +184,6 @@ class Context {
     getSignatureComment(declaration) {
         return (0, comments_1.getSignatureComment)(declaration, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
     }
-    /**
-     * @param callback  The callback function that should be executed with the changed context.
-     */
     withScope(scope) {
         const context = new Context(this.converter, this.programs, this.project, scope);
         context.convertingTypeNode = this.convertingTypeNode;

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

@@ -117,7 +117,6 @@ export declare class Converter extends ChildableComponent<Application, Converter
      * Convert the given TypeScript type into its TypeDoc type reflection.
      *
      * @param context  The context object describing the current state the converter is in.
-     * @param referenceTarget The target to be used to attempt to resolve reference types
      * @returns The TypeDoc type reflection representing the given node and type.
      * @internal
      */

package/dist/lib/converter/converter.js

@@ -203,7 +203,6 @@ let Converter = (() => {
          * Convert the given TypeScript type into its TypeDoc type reflection.
          *
          * @param context  The context object describing the current state the converter is in.
-         * @param referenceTarget The target to be used to attempt to resolve reference types
          * @returns The TypeDoc type reflection representing the given node and type.
          * @internal
          */

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

@@ -47,6 +47,9 @@ function createSignature(context, kind, signature, symbol, declaration) {
     else if (kind == models_1.ReflectionKind.SetSignature) {
         sigRef.type = new models_1.IntrinsicType("void");
     }
+    else if (declaration?.type?.kind === typescript_1.default.SyntaxKind.ThisType) {
+        sigRef.type = new models_1.IntrinsicType("this");
+    }
     else {
         sigRef.type = context.converter.convertType(sigRefCtx, (declaration?.kind === typescript_1.default.SyntaxKind.FunctionDeclaration &&
             declaration.type) ||
@@ -89,7 +92,14 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         else {
             type = param.type;
         }
-        paramRefl.type = context.converter.convertType(context.withScope(paramRefl), type);
+        if (declaration &&
+            typescript_1.default.isParameter(declaration) &&
+            declaration.type?.kind === typescript_1.default.SyntaxKind.ThisType) {
+            paramRefl.type = new models_1.IntrinsicType("this");
+        }
+        else {
+            paramRefl.type = context.converter.convertType(context.withScope(paramRefl), type);
+        }
         let isOptional = false;
         if (declaration) {
             isOptional = typescript_1.default.isParameter(declaration)
@@ -114,6 +124,7 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
                     typescript_1.default.isJSDocVariadicType(declaration.typeExpression.type);
         }
         paramRefl.setFlag(models_1.ReflectionFlag.Rest, isRest);
+        checkForDestructuredParameterDefaults(paramRefl, parameterNodes?.[i]);
         return paramRefl;
     });
 }
@@ -140,10 +151,27 @@ function convertParameterNodes(context, sigRef, parameters) {
             ? !!param.dotDotDotToken
             : !!param.typeExpression &&
                 typescript_1.default.isJSDocVariadicType(param.typeExpression.type));
+        checkForDestructuredParameterDefaults(paramRefl, param);
         return paramRefl;
     });
 }
 exports.convertParameterNodes = convertParameterNodes;
+function checkForDestructuredParameterDefaults(param, decl) {
+    if (!decl || !typescript_1.default.isParameter(decl))
+        return;
+    if (param.name !== "__namedParameters")
+        return;
+    if (!typescript_1.default.isObjectBindingPattern(decl.name))
+        return;
+    if (param.type?.type !== "reflection")
+        return;
+    for (const child of param.type.declaration.children || []) {
+        const tsChild = decl.name.elements.find((el) => (el.propertyName || el.name).getText() === child.name);
+        if (tsChild) {
+            child.defaultValue = (0, convert_expression_1.convertDefaultValue)(tsChild);
+        }
+    }
+}
 function convertTypeParameters(context, parent, parameters) {
     return parameters?.map((param) => {
         const constraintT = param.getConstraint();
@@ -218,8 +246,6 @@ function convertTemplateParameterNodes(context, nodes) {
             return paramRefl;
         });
     });
-    const params = (nodes ?? []).flatMap((tag) => tag.typeParameters);
-    return convertTypeParameterNodes(context, params);
 }
 exports.convertTemplateParameterNodes = convertTemplateParameterNodes;
 function getVariance(modifiers) {

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

@@ -22,13 +22,6 @@ export declare class CategoryPlugin extends ConverterComponent {
      * Triggered when the converter begins converting a project.
      */
     private onBegin;
-    /**
-     * Triggered when the converter resolves a reflection.
-     *
-     * @param context  The context object describing the current state the converter is in.
-     * @param reflection  The reflection that is currently resolved.
-     */
-    private onResolve;
     /**
      * Triggered when the converter has finished resolving a project.
      *

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

@@ -100,7 +100,6 @@ let CategoryPlugin = (() => {
         initialize() {
             this.listenTo(this.owner, {
                 [converter_1.Converter.EVENT_BEGIN]: this.onBegin,
-                [converter_1.Converter.EVENT_RESOLVE]: this.onResolve,
                 [converter_1.Converter.EVENT_RESOLVE_END]: this.onEndResolve,
             }, undefined, -200);
         }
@@ -117,17 +116,6 @@ let CategoryPlugin = (() => {
                 CategoryPlugin.WEIGHTS = this.categoryOrder;
             }
         }
-        /**
-         * Triggered when the converter resolves a reflection.
-         *
-         * @param context  The context object describing the current state the converter is in.
-         * @param reflection  The reflection that is currently resolved.
-         */
-        onResolve(_context, reflection) {
-            if (reflection instanceof models_1.ContainerReflection) {
-                this.categorize(reflection);
-            }
-        }
         /**
          * Triggered when the converter has finished resolving a project.
          *
@@ -136,6 +124,12 @@ let CategoryPlugin = (() => {
         onEndResolve(context) {
             const project = context.project;
             this.categorize(project);
+            for (const id in project.reflections) {
+                const reflection = project.reflections[id];
+                if (reflection instanceof models_1.ContainerReflection) {
+                    this.categorize(reflection);
+                }
+            }
             const unusedBoosts = new Set(Object.keys(this.boosts));
             for (const boost of this.usedBoosts) {
                 unusedBoosts.delete(boost);

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

@@ -121,4 +121,5 @@ export declare class CommentPlugin extends ConverterComponent {
      */
     private isHidden;
     private excludedByCategory;
+    private validateParamTags;
 }

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

@@ -382,13 +382,8 @@ let CommentPlugin = (() => {
             const comment = reflection.kindOf(models_1.ReflectionKind.ClassOrInterface)
                 ? undefined
                 : reflection.comment;
-            // Since this reflection has signatures, remove the comment from the parent
-            // reflection. This is important so that in type aliases we don't end up with
-            // a comment rendered twice.
-            if (!reflection.kindOf(models_1.ReflectionKind.ClassOrInterface)) {
-                delete reflection.comment;
-            }
             for (const signature of signatures) {
+                const signatureHadOwnComment = !!signature.comment;
                 const childComment = (signature.comment ||= comment?.clone());
                 if (!childComment)
                     continue;
@@ -400,7 +395,6 @@ let CommentPlugin = (() => {
                             parameter.name = commentParams[index].name;
                         }
                     }
-                    moveNestedParamTags(childComment, parameter);
                     const tag = childComment.getIdentifiedTag(parameter.name, "@param");
                     if (tag) {
                         parameter.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
@@ -414,10 +408,26 @@ let CommentPlugin = (() => {
                         parameter.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
                     }
                 }
+                this.validateParamTags(signature, childComment, signature.parameters || [], signatureHadOwnComment);
                 childComment?.removeTags("@param");
                 childComment?.removeTags("@typeParam");
                 childComment?.removeTags("@template");
             }
+            // Since this reflection has signatures, we need to remove the comment from the non-primary
+            // declaration location. For functions, this means removing it from the Function reflection.
+            // For type aliases, this means removing it from reflection.type.declaration.
+            // This is important so that in type aliases we don't end up with a comment rendered twice.
+            if (reflection.kindOf(models_1.ReflectionKind.FunctionOrMethod | models_1.ReflectionKind.Constructor)) {
+                delete reflection.comment;
+            }
+            if (reflection.kindOf(models_1.ReflectionKind.TypeAlias)) {
+                reflection.comment?.removeTags("@param");
+                reflection.comment?.removeTags("@typeParam");
+                reflection.comment?.removeTags("@template");
+                for (const sig of signatures) {
+                    delete sig.comment;
+                }
+            }
         }
         removeExcludedTags(comment) {
             for (const tag of NEVER_RENDERED) {
@@ -512,6 +522,16 @@ let CommentPlugin = (() => {
             }
             return excludeCategories.some((cat) => categories.has(cat));
         }
+        validateParamTags(signature, comment, params, signatureHadOwnComment) {
+            const paramTags = comment.blockTags.filter((tag) => tag.tag === "@param");
+            (0, utils_1.removeIf)(paramTags, (tag) => params.some((param) => param.name === tag.name));
+            moveNestedParamTags(/* in-out */ paramTags, params);
+            if (signatureHadOwnComment && paramTags.length) {
+                for (const tag of paramTags) {
+                    this.application.logger.warn(`The signature ${signature.getFriendlyFullName()} has an @param with name "${tag.name}", which was not used.`);
+                }
+            }
+        }
     };
     _CommentPlugin_excludeTags_accessor_storage = new WeakMap();
     _CommentPlugin_excludeInternal_accessor_storage = new WeakMap();
@@ -555,29 +575,39 @@ function inTypeLiteral(refl) {
     return false;
 }
 // Moves tags like `@param foo.bar docs for bar` into the `bar` property of the `foo` parameter.
-function moveNestedParamTags(comment, parameter) {
-    const visitor = {
-        reflection(target) {
-            const tags = comment.blockTags.filter((t) => t.tag === "@param" &&
-                t.name?.startsWith(`${parameter.name}.`));
-            for (const tag of tags) {
-                const path = tag.name.split(".");
-                path.shift();
-                const child = target.declaration.getChildByName(path);
-                if (child && !child.comment) {
-                    child.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+function moveNestedParamTags(
+/* in-out */ paramTags, parameters) {
+    const used = new Set();
+    for (const param of parameters) {
+        const visitor = {
+            reflection(target) {
+                const tags = paramTags.filter((t) => t.name?.startsWith(`${param.name}.`));
+                for (const tag of tags) {
+                    const path = tag.name.split(".");
+                    path.shift();
+                    const child = target.declaration.getChildByName(path);
+                    if (child && !child.comment) {
+                        child.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+                        used.add(paramTags.indexOf(tag));
+                    }
                 }
-            }
-        },
-        // #1876, also do this for unions/intersections.
-        union(u) {
-            u.types.forEach((t) => t.visit(visitor));
-        },
-        intersection(i) {
-            i.types.forEach((t) => t.visit(visitor));
-        },
-    };
-    parameter.type?.visit(visitor);
+            },
+            // #1876, also do this for unions/intersections.
+            union(u) {
+                u.types.forEach((t) => t.visit(visitor));
+            },
+            intersection(i) {
+                i.types.forEach((t) => t.visit(visitor));
+            },
+        };
+        param.type?.visit(visitor);
+    }
+    const toRemove = Array.from(used)
+        .sort((a, b) => a - b)
+        .reverse();
+    for (const index of toRemove) {
+        paramTags.splice(index, 1);
+    }
 }
 function movePropertyTags(comment, container) {
     const propTags = comment.blockTags.filter((tag) => tag.tag === "@prop" || tag.tag === "@property");

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

@@ -17,13 +17,6 @@ export declare class GroupPlugin extends ConverterComponent {
      * Create a new GroupPlugin instance.
      */
     initialize(): void;
-    /**
-     * Triggered when the converter resolves a reflection.
-     *
-     * @param context  The context object describing the current state the converter is in.
-     * @param reflection  The reflection that is currently resolved.
-     */
-    private onResolve;
     /**
      * Triggered when the converter has finished resolving a project.
      *

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

@@ -100,20 +100,8 @@ let GroupPlugin = (() => {
                     this.sortFunction = (0, sort_1.getSortFunction)(this.application.options);
                     GroupPlugin.WEIGHTS = this.groupOrder;
                 },
-                [converter_1.Converter.EVENT_RESOLVE]: this.onResolve,
                 [converter_1.Converter.EVENT_RESOLVE_END]: this.onEndResolve,
-            });
-        }
-        /**
-         * Triggered when the converter resolves a reflection.
-         *
-         * @param context  The context object describing the current state the converter is in.
-         * @param reflection  The reflection that is currently resolved.
-         */
-        onResolve(_context, reflection) {
-            if (reflection instanceof index_1.ContainerReflection) {
-                this.group(reflection);
-            }
+            }, undefined, -100);
         }
         /**
          * Triggered when the converter has finished resolving a project.
@@ -122,6 +110,12 @@ let GroupPlugin = (() => {
          */
         onEndResolve(context) {
             this.group(context.project);
+            for (const id in context.project.reflections) {
+                const reflection = context.project.reflections[id];
+                if (reflection instanceof index_1.ContainerReflection) {
+                    this.group(reflection);
+                }
+            }
             const unusedBoosts = new Set(Object.keys(this.boosts));
             for (const boost of this.usedBoosts) {
                 unusedBoosts.delete(boost);

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

@@ -196,6 +196,9 @@ let SourcePlugin = (() => {
                     refl instanceof index_1.SignatureReflection)) {
                     continue;
                 }
+                if (replaceSourcesWithParentSources(refl)) {
+                    refl.sources = refl.parent.sources;
+                }
                 for (const source of refl.sources || []) {
                     if (this.disableGit || (0, repository_1.gitIsInstalled)()) {
                         const repo = this.getRepository(basePath, source.fullFileName);
@@ -273,3 +276,23 @@ function getLocationNode(node) {
         return node.name;
     return node;
 }
+function replaceSourcesWithParentSources(refl) {
+    if (refl instanceof index_1.DeclarationReflection || !refl.sources) {
+        return false;
+    }
+    const symbol = refl.project.getSymbolFromReflection(refl.parent);
+    if (!symbol?.declarations) {
+        return false;
+    }
+    for (const decl of symbol.declarations) {
+        const file = decl.getSourceFile();
+        const pos = file.getLineAndCharacterOfPosition(decl.pos);
+        const end = file.getLineAndCharacterOfPosition(decl.end);
+        if (refl.sources.some((src) => src.fullFileName === file.fileName &&
+            pos.line <= src.line - 1 &&
+            src.line - 1 <= end.line)) {
+            return false;
+        }
+    }
+    return true;
+}

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

@@ -156,7 +156,10 @@ let TypePlugin = (() => {
                 if (reflection.extendedBy) {
                     push(reflection.extendedBy);
                 }
-                reflection.typeHierarchy = root;
+                // No point setting up a hierarchy if there is no hierarchy to display
+                if (root.next) {
+                    reflection.typeHierarchy = root;
+                }
             });
         }
     };