typedoc 0.28.19 → 0.28.20

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

@@ -1,241 +0,0 @@
-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.js

@@ -1,10 +0,0 @@
-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.js

@@ -1,279 +0,0 @@
-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];
-    }
-}