@depup/typedoc 0.28.17-depup.0

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

@@ -0,0 +1,241 @@
+import ts from "typescript";
+import { Comment, ReflectionKind } from "../../models/index.js";
+import { lexBlockComment } from "./blockLexer.js";
+import { discoverComment, discoverFileComments, discoverNodeComment, discoverSignatureComment, } from "./discovery.js";
+import { lexLineComments } from "./lineLexer.js";
+import { parseComment } from "./parser.js";
+import { assertNever, i18n, Logger, setUnion } from "#utils";
+const jsDocCommentKinds = [
+    ts.SyntaxKind.JSDocPropertyTag,
+    ts.SyntaxKind.JSDocCallbackTag,
+    ts.SyntaxKind.JSDocTypedefTag,
+    ts.SyntaxKind.JSDocTemplateTag,
+    ts.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.
+export function clearCommentCache() {
+    commentCache = new WeakMap();
+    commentDiscoveryId = 0;
+}
+function getCommentIgnoringCacheNoDiscoveryId(discovered, context) {
+    if (!discovered)
+        return;
+    const { file, ranges, jsDoc } = discovered;
+    let comment;
+    switch (ranges[0].kind) {
+        case ts.SyntaxKind.MultiLineCommentTrivia:
+            comment = parseComment(lexBlockComment(file.text, ranges[0].pos, ranges[0].end, context.createSymbolId, jsDoc, context.checker), file, context);
+            break;
+        case ts.SyntaxKind.SingleLineCommentTrivia:
+            comment = parseComment(lexLineComments(file.text, ranges), file, context);
+            break;
+        default:
+            assertNever(ranges[0].kind);
+    }
+    comment.inheritedFromParentDeclaration = discovered.inheritedFromParentDeclaration;
+    return comment;
+}
+function getCommentWithCache(discovered, context) {
+    if (!discovered)
+        return;
+    const { file, ranges } = discovered;
+    const cache = commentCache.get(file) || new Map();
+    if (cache.has(ranges[0].pos)) {
+        const clone = cache.get(ranges[0].pos).clone();
+        clone.inheritedFromParentDeclaration = discovered.inheritedFromParentDeclaration;
+        return clone;
+    }
+    const comment = getCommentIgnoringCacheNoDiscoveryId(discovered, context);
+    if (!comment)
+        return;
+    comment.discoveryId = ++commentDiscoveryId;
+    cache.set(ranges[0].pos, comment);
+    commentCache.set(file, cache);
+    return comment.clone();
+}
+function getCommentImpl(commentSource, moduleComment, context) {
+    const comment = getCommentWithCache(commentSource, {
+        ...context,
+        checker: context.config.useTsLinkResolution ? context.checker : undefined,
+    });
+    if (comment?.getTag("@import") || comment?.getTag("@license")) {
+        return;
+    }
+    if (moduleComment && comment) {
+        // Module comment, make sure it is tagged with @packageDocumentation or @module.
+        // If it isn't then the comment applies to the first statement in the file, so throw it away.
+        if (!comment.hasModifier("@packageDocumentation") &&
+            !comment.getTag("@module")) {
+            return;
+        }
+    }
+    if (!moduleComment && comment) {
+        // Ensure module comments are not attached to non-module reflections.
+        if (comment.hasModifier("@packageDocumentation") ||
+            comment.getTag("@module")) {
+            return;
+        }
+    }
+    return comment;
+}
+export function getComment(symbol, kind, context) {
+    const declarations = symbol.declarations || [];
+    if (declarations.length &&
+        declarations.every((d) => jsDocCommentKinds.includes(d.kind))) {
+        return getJsDocComment(declarations[0], context);
+    }
+    const sf = declarations.find(ts.isSourceFile);
+    if (sf) {
+        return getFileComment(sf, context);
+    }
+    const isModule = declarations.some((decl) => {
+        if (ts.isModuleDeclaration(decl) && ts.isStringLiteral(decl.name)) {
+            return true;
+        }
+        return false;
+    });
+    const comment = getCommentImpl(discoverComment(symbol, kind, context.logger, context.config.commentStyle, context.checker, !context.config.suppressCommentWarningsInDeclarationFiles), isModule, context);
+    if (!comment && kind === ReflectionKind.Property) {
+        return getConstructorParamPropertyComment(symbol, context);
+    }
+    return comment;
+}
+export function getNodeComment(node, moduleComment, context) {
+    return getCommentImpl(discoverNodeComment(node, context.config.commentStyle), moduleComment, context);
+}
+export function getFileComment(file, context) {
+    const quietContext = {
+        ...context,
+        logger: new Logger(),
+    };
+    for (const commentSource of discoverFileComments(file, context.config.commentStyle)) {
+        // First parse the comment without adding the parse to the cache
+        // and without logging any messages. If we end up not using this as
+        // a file comment we want to avoid parsing it with warnings here as
+        // it might be associated with a JSDoc parse which has special
+        // handling to allow modifier tags to be specified as {@mod}
+        // and if it gets added to the cache here we'll get unwanted warnings
+        const comment = getCommentIgnoringCacheNoDiscoveryId(commentSource, quietContext);
+        if (comment?.getTag("@license") || comment?.getTag("@import")) {
+            continue;
+        }
+        if (comment?.getTag("@module") ||
+            comment?.hasModifier("@packageDocumentation")) {
+            return getCommentWithCache(commentSource, context);
+        }
+        return;
+    }
+}
+function getConstructorParamPropertyComment(symbol, context) {
+    const decl = symbol.declarations?.find(ts.isParameter);
+    if (!decl)
+        return;
+    const ctor = decl.parent;
+    const comment = getSignatureComment(ctor, context);
+    const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
+    if (paramTag) {
+        const result = new Comment(paramTag.content);
+        result.sourcePath = comment.sourcePath;
+        return result;
+    }
+}
+export function getSignatureComment(declaration, context) {
+    return getCommentImpl(discoverSignatureComment(declaration, context.checker, context.config.commentStyle), false, context);
+}
+function buildJsDocCommentFromParts(declaration, parts, sourceComment, context) {
+    if (!parts) {
+        return undefined;
+    }
+    const comment = new Comment(Comment.cloneDisplayParts(parts));
+    comment.sourcePath = sourceComment.sourcePath;
+    for (let i = 0; i < comment.summary.length;) {
+        const part = comment.summary[i];
+        if (part.kind === "inline-tag" &&
+            !part.text.trim() &&
+            context.config.modifierTags.has(part.tag)) {
+            comment.modifierTags.add(part.tag);
+            comment.summary.splice(i, 1);
+        }
+        else if (part.kind === "inline-tag" &&
+            part.text.trim() &&
+            context.config.modifierTags.has(part.tag) &&
+            !context.config.inlineTags.has(part.tag)) {
+            context.logger.warn(i18n.inline_tag_0_not_parsed_as_modifier_tag_1(part.tag, part.text.trim()), declaration);
+            ++i;
+        }
+        else {
+            ++i;
+        }
+    }
+    return comment;
+}
+export function getJsDocComment(declaration, context) {
+    const file = declaration.getSourceFile();
+    // First, get the whole comment. We know we'll need all of it.
+    let parent = declaration.parent;
+    while (!ts.isJSDoc(parent)) {
+        parent = parent.parent;
+    }
+    // Build a custom context to allow modifier tags to be written as inline
+    // tags as otherwise there's no way to specify them here #2916 #3050
+    const contextWithInline = {
+        ...context,
+        config: {
+            ...context.config,
+            inlineTags: setUnion(context.config.inlineTags, context.config.modifierTags),
+        },
+    };
+    // Then parse it.
+    const comment = getCommentWithCache({
+        file,
+        ranges: [
+            {
+                kind: ts.SyntaxKind.MultiLineCommentTrivia,
+                pos: parent.pos,
+                end: parent.end,
+            },
+        ],
+        jsDoc: parent,
+        inheritedFromParentDeclaration: false,
+    }, contextWithInline);
+    // And pull out the tag we actually care about.
+    if (ts.isJSDocEnumTag(declaration)) {
+        return buildJsDocCommentFromParts(declaration, comment.getTag("@enum")?.content, comment, context);
+    }
+    if (ts.isJSDocTemplateTag(declaration) &&
+        declaration.comment &&
+        declaration.typeParameters.length > 1) {
+        // 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.
+        context.logger.warn(i18n.multiple_type_parameters_on_template_tag_unsupported(), declaration);
+        return;
+    }
+    let name;
+    if (ts.isJSDocTemplateTag(declaration)) {
+        // This isn't really ideal.
+        name = declaration.typeParameters[0].name.text;
+    }
+    else {
+        name = declaration.name?.getText();
+    }
+    if (!name) {
+        return;
+    }
+    const tag = comment.getIdentifiedTag(name, `@${declaration.tagName.text}`);
+    if (!tag) {
+        // If this is a template tag with multiple declarations, we warned already if there
+        // was a comment attached. If there wasn't, then don't error about failing to find
+        // a tag because this is unsupported.
+        if (!ts.isJSDocTemplateTag(declaration)) {
+            context.logger.error(i18n.failed_to_find_jsdoc_tag_for_name_0(name), declaration);
+        }
+    }
+    else {
+        return buildJsDocCommentFromParts(declaration, tag.content, comment, context);
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { ReflectionSymbolId } from "../../models/index.js";
+export declare enum TokenSyntaxKind {
+    Text = "text",
+    NewLine = "new_line",
+    OpenBrace = "open_brace",
+    CloseBrace = "close_brace",
+    Tag = "tag",
+    Code = "code",
+    TypeAnnotation = "type"
+}
+export interface Token {
+    kind: TokenSyntaxKind;
+    text: string;
+    pos: number;
+    tsLinkTarget?: ReflectionSymbolId;
+    tsLinkText?: string;
+}

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

@@ -0,0 +1,10 @@
+export var TokenSyntaxKind;
+(function (TokenSyntaxKind) {
+    TokenSyntaxKind["Text"] = "text";
+    TokenSyntaxKind["NewLine"] = "new_line";
+    TokenSyntaxKind["OpenBrace"] = "open_brace";
+    TokenSyntaxKind["CloseBrace"] = "close_brace";
+    TokenSyntaxKind["Tag"] = "tag";
+    TokenSyntaxKind["Code"] = "code";
+    TokenSyntaxKind["TypeAnnotation"] = "type";
+})(TokenSyntaxKind || (TokenSyntaxKind = {}));

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

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

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

@@ -0,0 +1,279 @@
+import { TokenSyntaxKind } from "./lexer.js";
+export function* lexLineComments(file, ranges) {
+    // Wrapper around our real lex function to collapse adjacent text tokens.
+    let textToken;
+    for (const token of lexLineComments2(file, ranges[0].pos, ranges[ranges.length - 1].end)) {
+        if (token.kind === TokenSyntaxKind.Text) {
+            if (textToken) {
+                textToken.text += token.text;
+            }
+            else {
+                textToken = token;
+            }
+        }
+        else {
+            if (textToken) {
+                yield textToken;
+                textToken = void 0;
+            }
+            yield token;
+        }
+    }
+    if (textToken) {
+        yield textToken;
+    }
+    return;
+}
+function* lexLineComments2(file, pos, end) {
+    // Trailing whitespace
+    while (pos < end && /\s/.test(file[end - 1])) {
+        end--;
+    }
+    let lineStart = true;
+    let braceStartsType = false;
+    for (;;) {
+        if (lineStart) {
+            pos = skipLeadingLineTrivia(pos);
+            lineStart = false;
+        }
+        if (pos >= end) {
+            return;
+        }
+        switch (file[pos]) {
+            case "\n":
+                yield makeToken(TokenSyntaxKind.NewLine, 1);
+                lineStart = true;
+                break;
+            case "{":
+                if (braceStartsType && nextNonWs(pos + 1) !== "@") {
+                    yield makeToken(TokenSyntaxKind.TypeAnnotation, findEndOfType(pos) - pos);
+                    braceStartsType = false;
+                }
+                else {
+                    yield makeToken(TokenSyntaxKind.OpenBrace, 1);
+                }
+                break;
+            case "}":
+                yield makeToken(TokenSyntaxKind.CloseBrace, 1);
+                braceStartsType = false;
+                break;
+            case "`": {
+                // Markdown's code rules are a royal pain. This could be one of several things.
+                // 1. Inline code: <1-n ticks><text><same number of ticks>
+                // 2. Code block: <3 ticks><language, no ticks>\n<text>\n<3 ticks>\n
+                // 3. Unmatched tick(s), not code, but part of some text.
+                // We don't quite handle #2 correctly yet. PR welcome!
+                braceStartsType = false;
+                let tickCount = 1;
+                let lookahead = pos - 1;
+                let atNewline = true;
+                while (lookahead > 0 && file[lookahead] !== "\n") {
+                    if (/\S/.test(file[lookahead])) {
+                        atNewline = false;
+                        break;
+                    }
+                    --lookahead;
+                }
+                lookahead = pos;
+                while (lookahead + 1 < end && file[lookahead + 1] === "`") {
+                    tickCount++;
+                    lookahead++;
+                }
+                const isCodeBlock = atNewline && tickCount >= 3;
+                let lookaheadStart = pos;
+                const codeText = [];
+                lookahead++;
+                while (lookahead < end) {
+                    if (lookaheadExactlyNTicks(lookahead, tickCount)) {
+                        lookahead += tickCount;
+                        codeText.push(file.substring(lookaheadStart, lookahead));
+                        const codeTextStr = codeText.join("");
+                        if (isCodeBlock || !/\n\s*\n/.test(codeTextStr)) {
+                            yield {
+                                kind: TokenSyntaxKind.Code,
+                                text: codeTextStr,
+                                pos,
+                            };
+                            pos = lookahead;
+                        }
+                        else {
+                            yield makeToken(TokenSyntaxKind.Text, tickCount);
+                        }
+                        break;
+                    }
+                    else if (file[lookahead] === "`") {
+                        while (lookahead < end && file[lookahead] === "`") {
+                            lookahead++;
+                        }
+                    }
+                    else if (file[lookahead] === "\\" &&
+                        lookahead + 1 < end &&
+                        file[lookahead + 1] !== "\n") {
+                        lookahead += 2;
+                    }
+                    else if (file[lookahead] === "\n") {
+                        lookahead++;
+                        codeText.push(file.substring(lookaheadStart, lookahead));
+                        lookahead = skipLeadingLineTrivia(lookahead);
+                        lookaheadStart = lookahead;
+                    }
+                    else {
+                        lookahead++;
+                    }
+                }
+                if (lookahead >= end && pos !== lookahead) {
+                    if (tickCount === 3 &&
+                        file.substring(pos, end).includes("\n")) {
+                        codeText.push(file.substring(lookaheadStart, end));
+                        yield {
+                            kind: TokenSyntaxKind.Code,
+                            text: codeText.join(""),
+                            pos,
+                        };
+                        pos = lookahead;
+                    }
+                    else {
+                        yield makeToken(TokenSyntaxKind.Text, tickCount);
+                    }
+                }
+                break;
+            }
+            case "@": {
+                let lookahead = pos + 1;
+                while (lookahead < end && /[a-z]/i.test(file[lookahead])) {
+                    lookahead++;
+                }
+                if (lookahead !== pos + 1) {
+                    while (lookahead < end &&
+                        /[a-z0-9-]/i.test(file[lookahead])) {
+                        lookahead++;
+                    }
+                }
+                if (lookahead !== pos + 1 &&
+                    (lookahead === end || /[\s}]/.test(file[lookahead]))) {
+                    braceStartsType = true;
+                    yield makeToken(TokenSyntaxKind.Tag, lookahead - pos);
+                    break;
+                }
+            }
+            // fall through if we didn't find something that looks like a tag
+            default: {
+                const textParts = [];
+                let lookaheadStart = pos;
+                let lookahead = pos;
+                while (lookahead < end) {
+                    if ("{}\n`".includes(file[lookahead]))
+                        break;
+                    if (lookahead !== pos &&
+                        file[lookahead] === "@" &&
+                        /\s/.test(file[lookahead - 1])) {
+                        // Probably the start of a modifier tag
+                        break;
+                    }
+                    if (file[lookahead] === "\\" &&
+                        lookahead + 1 < end &&
+                        "{}@`".includes(file[lookahead + 1])) {
+                        textParts.push(file.substring(lookaheadStart, lookahead), file[lookahead + 1]);
+                        lookahead++;
+                        lookaheadStart = lookahead + 1;
+                    }
+                    lookahead++;
+                }
+                textParts.push(file.substring(lookaheadStart, lookahead));
+                if (textParts.some((part) => /\S/.test(part))) {
+                    braceStartsType = false;
+                }
+                // This piece of text had line continuations or escaped text
+                yield {
+                    kind: TokenSyntaxKind.Text,
+                    text: textParts.join(""),
+                    pos,
+                };
+                pos = lookahead;
+                break;
+            }
+        }
+    }
+    function makeToken(kind, size) {
+        const start = pos;
+        pos += size;
+        return {
+            kind,
+            text: file.substring(start, pos),
+            pos: start,
+        };
+    }
+    function skipLeadingLineTrivia(pos) {
+        let lookahead = pos;
+        while (lookahead < end && /\s/.test(file[lookahead])) {
+            lookahead++;
+        }
+        while (lookahead < end && file[lookahead] === "/") {
+            lookahead++;
+        }
+        if (lookahead < end && file[lookahead] === " ") {
+            lookahead++;
+        }
+        return lookahead;
+    }
+    function lookaheadExactlyNTicks(pos, n) {
+        if (pos + n > end) {
+            return false;
+        }
+        return file.startsWith("`".repeat(n), pos) && file[pos + n] !== "`";
+    }
+    function findEndOfType(pos) {
+        let openBraces = 0;
+        while (pos < end) {
+            if (file[pos] === "{") {
+                openBraces++;
+            }
+            else if (file[pos] === "}") {
+                if (--openBraces === 0) {
+                    break;
+                }
+            }
+            else if ("`'\"".includes(file[pos])) {
+                pos = findEndOfString(pos);
+            }
+            pos++;
+        }
+        if (pos < end && file[pos] === "}") {
+            pos++;
+        }
+        return pos;
+    }
+    function findEndOfString(pos) {
+        const endOfString = file[pos];
+        pos++;
+        while (pos < end) {
+            if (file[pos] === endOfString) {
+                break;
+            }
+            else if (file[pos] === "\\") {
+                pos++; // Skip escaped character
+            }
+            else if (endOfString === "`" &&
+                file[pos] === "$" &&
+                file[pos + 1] === "{") {
+                // Template literal with data inside a ${}
+                while (pos < end && file[pos] !== "}") {
+                    if ("`'\"".includes(file[pos])) {
+                        pos = findEndOfString(pos) + 1;
+                    }
+                    else {
+                        pos++;
+                    }
+                }
+            }
+            pos++;
+        }
+        return pos;
+    }
+    function nextNonWs(pos) {
+        while (pos < end && /\s/.test(file[pos])) {
+            pos++;
+        }
+        return file[pos];
+    }
+}

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

@@ -0,0 +1,20 @@
+import { type CommentDisplayPart, Reflection, ReflectionSymbolId } from "../../models/index.js";
+import { type DeclarationReference } from "#utils";
+export type ExternalResolveResult = {
+    target: string;
+    caption?: string;
+};
+/**
+ * @param ref - Parsed declaration reference to resolve. This may be created automatically for some symbol, or
+ *   parsed from user input.
+ * @param refl - Reflection that contains the resolved link
+ * @param part - If the declaration reference was created from a comment, the originating part.
+ * @param symbolId - If the declaration reference was created from a symbol, or `useTsLinkResolution` is turned
+ *   on and TypeScript resolved the link to some symbol, the ID of that symbol.
+ */
+export type ExternalSymbolResolver = (ref: DeclarationReference, refl: Reflection, part: Readonly<CommentDisplayPart> | undefined, symbolId: ReflectionSymbolId | undefined) => ExternalResolveResult | string | undefined;
+export type LinkResolverOptions = {
+    preserveLinkText: boolean;
+};
+export declare function resolveLinks(reflection: Reflection, externalResolver: ExternalSymbolResolver, options: LinkResolverOptions): void;
+export declare function resolvePartLinks(reflection: Reflection, parts: readonly CommentDisplayPart[], externalResolver: ExternalSymbolResolver, options: LinkResolverOptions): CommentDisplayPart[];