typedoc 0.25.13 → 0.26.0-beta.0

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

@@ -3,7 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.discoverSignatureComment = exports.discoverComment = exports.discoverNodeComment = exports.discoverFileComment = void 0;
+exports.discoverFileComments = discoverFileComments;
+exports.discoverNodeComment = discoverNodeComment;
+exports.discoverComment = discoverComment;
+exports.discoverSignatureComment = discoverSignatureComment;
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../../models");
 const utils_1 = require("../../utils");
@@ -106,20 +109,21 @@ const wantedKinds = {
         typescript_1.default.SyntaxKind.NamespaceExport,
         typescript_1.default.SyntaxKind.ExportSpecifier,
     ],
+    // Non-TS kind, will never have comments.
+    [models_1.ReflectionKind.Document]: [],
 };
-function discoverFileComment(node, commentStyle) {
+function discoverFileComments(node, commentStyle) {
     const text = node.text;
     const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
-    const selectedDocComment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
-    if (selectedDocComment) {
+    const selectedDocComments = comments.filter((ranges) => permittedRange(text, ranges, commentStyle));
+    return selectedDocComments.map((ranges) => {
         return {
             file: node,
-            ranges: selectedDocComment,
-            jsDoc: findJsDocForComment(node, selectedDocComment),
+            ranges,
+            jsDoc: findJsDocForComment(node, ranges),
         };
-    }
+    });
 }
-exports.discoverFileComment = discoverFileComment;
 function discoverNodeComment(node, commentStyle) {
     const text = node.getSourceFile().text;
     const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
@@ -133,7 +137,6 @@ function discoverNodeComment(node, commentStyle) {
         };
     }
 }
-exports.discoverNodeComment = discoverNodeComment;
 function discoverComment(symbol, kind, logger, commentStyle) {
     // 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.
@@ -148,18 +151,19 @@ function discoverComment(symbol, kind, logger, commentStyle) {
                 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.
-            // However, we don't want to skip the node if it is a reference to something.
-            // See the gh1770 test for an example.
+            // Special behavior here!
+            // Signatures and symbols have two distinct discovery methods as of TypeDoc 0.26.
+            // This method discovers comments for symbols, and function-likes will only have
+            // a symbol comment if there is more than one signature (== more than one declaration)
+            // and there is a comment on the implementation signature.
             if (kind & models_1.ReflectionKind.ContainsCallSignatures &&
                 [
                     typescript_1.default.SyntaxKind.FunctionDeclaration,
                     typescript_1.default.SyntaxKind.MethodDeclaration,
                     typescript_1.default.SyntaxKind.Constructor,
                 ].includes(node.kind) &&
-                !node.body) {
+                (symbol.declarations.filter((d) => wantedKinds[kind].includes(d.kind)).length === 1 ||
+                    !node.body)) {
                 continue;
             }
             const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
@@ -182,18 +186,17 @@ function discoverComment(symbol, kind, logger, commentStyle) {
         case 1:
             return discovered[0];
         default: {
-            logger.warn(`${symbol.name} has multiple declarations with a comment. An arbitrary comment will be used.`);
+            logger.warn(logger.i18n.symbol_0_has_multiple_declarations_with_comment(symbol.name));
             const locations = discovered.map(({ file, ranges: [{ pos }] }) => {
                 const path = (0, paths_1.nicePath)(file.fileName);
                 const line = typescript_1.default.getLineAndCharacterOfPosition(file, pos).line + 1;
                 return `${path}:${line}`;
             });
-            logger.info(`The comments for ${symbol.name} are declared at:\n\t${locations.join("\n\t")}`);
+            logger.info(logger.i18n.comments_for_0_are_declared_at_1(symbol.name, locations.join("\n\t")));
             return discovered[0];
         }
     }
 }
-exports.discoverComment = discoverComment;
 function discoverSignatureComment(declaration, commentStyle) {
     const node = declarationToCommentNode(declaration);
     if (!node) {
@@ -226,7 +229,6 @@ function discoverSignatureComment(declaration, commentStyle) {
         };
     }
 }
-exports.discoverSignatureComment = discoverSignatureComment;
 function findJsDocForComment(node, ranges) {
     if (ranges[0].kind === typescript_1.default.SyntaxKind.MultiLineCommentTrivia) {
         const jsDocs = typescript_1.default

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

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import { Comment, ReflectionKind } from "../../models";
-import { Logger } from "../../utils";
+import { type Logger } from "../../utils";
 import type { CommentStyle, JsDocCompatibility } from "../../utils/options/declaration";
 export interface CommentParserConfig {
     blockTags: Set<string>;

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

@@ -3,7 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getJsDocComment = exports.getSignatureComment = exports.getFileComment = exports.getNodeComment = exports.getComment = exports.clearCommentCache = void 0;
+exports.clearCommentCache = clearCommentCache;
+exports.getComment = getComment;
+exports.getNodeComment = getNodeComment;
+exports.getFileComment = getFileComment;
+exports.getSignatureComment = getSignatureComment;
+exports.getJsDocComment = getJsDocComment;
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../../models");
 const utils_1 = require("../../utils");
@@ -18,14 +23,15 @@ const jsDocCommentKinds = [
     typescript_1.default.SyntaxKind.JSDocTemplateTag,
     typescript_1.default.SyntaxKind.JSDocEnumTag,
 ];
+let commentDiscoveryId = 0;
 let commentCache = new WeakMap();
 // We need to do this for tests so that changing the tsLinkResolution option
 // actually works. Without it, we'd get the old parsed comment which doesn't
 // have the TS symbols attached.
 function clearCommentCache() {
     commentCache = new WeakMap();
+    commentDiscoveryId = 0;
 }
-exports.clearCommentCache = clearCommentCache;
 function getCommentWithCache(discovered, config, logger, checker) {
     if (!discovered)
         return;
@@ -45,6 +51,7 @@ function getCommentWithCache(discovered, config, logger, checker) {
         default:
             (0, utils_1.assertNever)(ranges[0].kind);
     }
+    comment.discoveryId = ++commentDiscoveryId;
     cache.set(ranges[0].pos, comment);
     commentCache.set(file, cache);
     return comment.clone();
@@ -74,9 +81,11 @@ function getComment(symbol, kind, config, logger, commentStyle, checker) {
         declarations.every((d) => jsDocCommentKinds.includes(d.kind))) {
         return getJsDocComment(declarations[0], config, logger, checker);
     }
+    const sf = declarations.find(typescript_1.default.isSourceFile);
+    if (sf) {
+        return getFileComment(sf, config, logger, commentStyle, checker);
+    }
     const isModule = declarations.some((decl) => {
-        if (typescript_1.default.isSourceFile(decl))
-            return true;
         if (typescript_1.default.isModuleDeclaration(decl) && typescript_1.default.isStringLiteral(decl.name)) {
             return true;
         }
@@ -88,16 +97,22 @@ function getComment(symbol, kind, config, logger, commentStyle, checker) {
     }
     return comment;
 }
-exports.getComment = getComment;
 function getNodeComment(node, kind, config, logger, commentStyle, checker) {
     return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, kind === models_1.ReflectionKind.Module, checker);
 }
-exports.getNodeComment = getNodeComment;
 function getFileComment(file, config, logger, commentStyle, checker) {
-    return getCommentImpl((0, discovery_1.discoverFileComment)(file, commentStyle), config, logger, 
-    /* moduleComment */ true, checker);
+    for (const commentSource of (0, discovery_1.discoverFileComments)(file, commentStyle)) {
+        const comment = getCommentWithCache(commentSource, config, logger, checker);
+        if (comment?.getTag("@license") || comment?.getTag("@import")) {
+            continue;
+        }
+        if (comment?.getTag("@module") ||
+            comment?.hasModifier("@packageDocumentation")) {
+            return comment;
+        }
+        return;
+    }
 }
-exports.getFileComment = getFileComment;
 function getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker) {
     const decl = symbol.declarations?.find(typescript_1.default.isParameter);
     if (!decl)
@@ -106,13 +121,14 @@ function getConstructorParamPropertyComment(symbol, config, logger, commentStyle
     const comment = getSignatureComment(ctor, config, logger, commentStyle, checker);
     const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
     if (paramTag) {
-        return new models_1.Comment(paramTag.content);
+        const result = new models_1.Comment(paramTag.content);
+        result.sourcePath = comment.sourcePath;
+        return result;
     }
 }
 function getSignatureComment(declaration, config, logger, commentStyle, checker) {
     return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, commentStyle), config, logger, false, checker);
 }
-exports.getSignatureComment = getSignatureComment;
 function getJsDocComment(declaration, config, logger, checker) {
     const file = declaration.getSourceFile();
     // First, get the whole comment. We know we'll need all of it.
@@ -134,7 +150,9 @@ function getJsDocComment(declaration, config, logger, checker) {
     }, config, logger, checker);
     // And pull out the tag we actually care about.
     if (typescript_1.default.isJSDocEnumTag(declaration)) {
-        return new models_1.Comment(comment.getTag("@enum")?.content);
+        const result = new models_1.Comment(comment.getTag("@enum")?.content);
+        result.sourcePath = comment.sourcePath;
+        return result;
     }
     if (typescript_1.default.isJSDocTemplateTag(declaration) &&
         declaration.comment &&
@@ -142,7 +160,7 @@ function getJsDocComment(declaration, config, logger, checker) {
         // We could just put the same comment on everything, but due to how comment parsing works,
         // we'd have to search for any @template with a name starting with the first type parameter's name
         // which feels horribly hacky.
-        logger.warn(`TypeDoc does not support multiple type parameters defined in a single @template tag with a comment.`, declaration);
+        logger.warn(logger.i18n.multiple_type_parameters_on_template_tag_unsupported(), declaration);
         return;
     }
     let name;
@@ -158,10 +176,11 @@ function getJsDocComment(declaration, config, logger, checker) {
     }
     const tag = comment.getIdentifiedTag(name, `@${declaration.tagName.text}`);
     if (!tag) {
-        logger.error(`Failed to find JSDoc tag for ${name} after parsing comment, please file a bug report.`, declaration);
+        logger.error(logger.i18n.failed_to_find_jsdoc_tag_for_name_0(name), declaration);
     }
     else {
-        return new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+        const result = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+        result.sourcePath = comment.sourcePath;
+        return result;
     }
 }
-exports.getJsDocComment = getJsDocComment;

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

@@ -1,3 +1,3 @@
 import type * as ts from "typescript";
-import { Token } from "./lexer";
+import { type Token } from "./lexer";
 export declare function lexLineComments(file: string, ranges: ts.CommentRange[]): Generator<Token, undefined, undefined>;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.lexLineComments = void 0;
+exports.lexLineComments = lexLineComments;
 const lexer_1 = require("./lexer");
 function* lexLineComments(file, ranges) {
     // Wrapper around our real lex function to collapse adjacent text tokens.
@@ -27,7 +27,6 @@ function* lexLineComments(file, ranges) {
     }
     return;
 }
-exports.lexLineComments = lexLineComments;
 function* lexLineComments2(file, pos, end) {
     // Trailing whitespace
     while (pos < end && /\s/.test(file[end - 1])) {

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

@@ -1,5 +1,5 @@
-import { Comment, CommentDisplayPart, Reflection, ReflectionSymbolId } from "../../models";
-import { DeclarationReference } from "./declarationReference";
+import { type Comment, type CommentDisplayPart, type Reflection, ReflectionSymbolId } from "../../models";
+import { type DeclarationReference } from "./declarationReference";
 export type ExternalResolveResult = {
     target: string;
     caption?: string;

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

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolvePartLinks = exports.resolveLinks = void 0;
+exports.resolveLinks = resolveLinks;
+exports.resolvePartLinks = resolvePartLinks;
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../../models");
 const declarationReference_1 = require("./declarationReference");
@@ -17,12 +18,13 @@ function resolveLinks(comment, reflection, externalResolver, options) {
     if (reflection instanceof models_1.DeclarationReflection && reflection.readme) {
         reflection.readme = resolvePartLinks(reflection, reflection.readme, externalResolver, options);
     }
+    if (reflection.isDocument()) {
+        reflection.content = resolvePartLinks(reflection, reflection.content, externalResolver, options);
+    }
 }
-exports.resolveLinks = resolveLinks;
 function resolvePartLinks(reflection, parts, externalResolver, options) {
     return parts.flatMap((part) => processPart(reflection, part, externalResolver, options));
 }
-exports.resolvePartLinks = resolvePartLinks;
 function processPart(reflection, part, externalResolver, options) {
     if (part.kind === "inline-tag") {
         if (part.tag === "@link" ||

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

@@ -1,6 +1,17 @@
 import type { CommentParserConfig } from ".";
-import { Comment } from "../../models";
-import { Logger } from "../../utils";
+import { Comment, type CommentDisplayPart } from "../../models";
+import { type Logger } from "../../utils";
 import type { MinimalSourceFile } from "../../utils/minimalSourceFile";
-import { Token } from "./lexer";
+import { type Token } from "./lexer";
 export declare function parseComment(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger): Comment;
+/**
+ * Intended for parsing markdown documents. This only parses code blocks and
+ * inline tags outside of code blocks, everything else is text.
+ *
+ * If you change this, also look at blockContent, as it likely needs similar
+ * modifications to ensure parsing is consistent.
+ */
+export declare function parseCommentString(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger): {
+    content: CommentDisplayPart[];
+    frontmatter: Record<string, unknown>;
+};