typedoc - npm Package Compare versions

Comparing version 0.23.2 to 0.23.3

dist/index.d.ts

@@ -9,3 +9,3 @@ export { Application } from "./lib/application";
 export type { RenderTemplate, RendererHooks } from "./lib/output";
-export { ArgumentsReader, BindOption, CommentStyle, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, } from "./lib/utils";
+export { ArgumentsReader, BindOption, CommentStyle, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, MinimalSourceFile, } from "./lib/utils";
 export type { OptionsReader, TypeDocOptions, TypeDocOptionMap, ValidationOptions, TypeDocOptionValues, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, ManuallyValidatedOption, } from "./lib/utils";
@@ -12,0 +12,0 @@ export type { EventMap, EventCallback } from "./lib/utils/events";

dist/index.js

@@ -17,3 +17,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeScript = exports.SerializeEvent = exports.Serializer = exports.JSONOutput = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.MarkdownEvent = exports.RendererEvent = exports.PageEvent = exports.Theme = exports.UrlMapping = exports.DefaultThemeRenderContext = exports.DefaultTheme = exports.Renderer = exports.Context = exports.Converter = exports.normalizePath = exports.resetReflectionID = exports.Event = exports.EventDispatcher = exports.Application = void 0;
+exports.TypeScript = exports.SerializeEvent = exports.Serializer = exports.JSONOutput = exports.MinimalSourceFile = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.MarkdownEvent = exports.RendererEvent = exports.PageEvent = exports.Theme = exports.UrlMapping = exports.DefaultThemeRenderContext = exports.DefaultTheme = exports.Renderer = exports.Context = exports.Converter = exports.normalizePath = exports.resetReflectionID = exports.Event = exports.EventDispatcher = exports.Application = void 0;
 var application_1 = require("./lib/application");
@@ -55,2 +55,3 @@ Object.defineProperty(exports, "Application", { enumerable: true, get: function () { return application_1.Application; } });
 Object.defineProperty(exports, "EventHooks", { enumerable: true, get: function () { return utils_1.EventHooks; } });
+Object.defineProperty(exports, "MinimalSourceFile", { enumerable: true, get: function () { return utils_1.MinimalSourceFile; } });
 var serialization_1 = require("./lib/serialization");
@@ -57,0 +58,0 @@ Object.defineProperty(exports, "JSONOutput", { enumerable: true, get: function () { return serialization_1.JSONOutput; } });

dist/lib/converter/comments/blockLexer.js

@@ -105,2 +105,3 @@ "use strict";
                             text: codeText.join(""),
+                            pos,
                         };
@@ -150,2 +151,3 @@ pos = lookahead;
                             text: codeText.join(""),
+                            pos,
                         };
@@ -204,3 +206,2 @@ pos = lookahead;
                 }
-                pos = lookahead;
                 // This piece of text had line continuations or escaped text
@@ -210,3 +211,5 @@ yield {
                     text: textParts.join(""),
+                    pos,
                 };
+                pos = lookahead;
                 break;
@@ -222,2 +225,3 @@ }
             text: file.substring(start, pos),
+            pos: start,
         };
@@ -224,0 +228,0 @@ }

dist/lib/converter/comments/declarationReference.d.ts

@@ -8,3 +8,3 @@ /**
  */
-export declare const MeaningKeywords: readonly ["class", "interface", "type", "enum", "namespace", "function", "var", "constructor", "member", "event", "call", "new", "index", "complex"];
+export declare const MeaningKeywords: readonly ["class", "interface", "type", "enum", "namespace", "function", "var", "constructor", "member", "event", "call", "new", "index", "complex", "getter", "setter"];
 export declare type MeaningKeyword = typeof MeaningKeywords[number];
@@ -11,0 +11,0 @@ export interface DeclarationReference {

dist/lib/converter/comments/declarationReference.js

@@ -25,3 +25,6 @@ "use strict";
     "index",
-    "complex", // Any complex type
+    "complex",
+    // TypeDoc specific
+    "getter",
+    "setter",
 ];
@@ -28,0 +31,0 @@ // <TAB> <VT> <FF> <SP> <NBSP> <ZWNBSP> <USP>

dist/lib/converter/comments/declarationReferenceResolver.js

@@ -140,2 +140,14 @@ "use strict";
             break;
+        case "getter":
+            if (refl.getSignature) {
+                return [refl.getSignature];
+            }
+            break;
+        case "setter":
+            if (refl.setSignature) {
+                return [refl.setSignature];
+            }
+            break;
+        default:
+            (0, utils_1.assertNever)(kw);
     }
@@ -142,0 +154,0 @@ }

dist/lib/converter/comments/discovery.js

@@ -21,2 +21,3 @@ "use strict";
         ts.SyntaxKind.ExportSpecifier,
+        ts.SyntaxKind.NamespaceExport,
     ],
@@ -37,2 +38,3 @@ [models_1.ReflectionKind.Enum]: [
         ts.SyntaxKind.ExportAssignment,
+        ts.SyntaxKind.PropertyAccessExpression,
     ],
@@ -73,6 +75,3 @@ [models_1.ReflectionKind.Function]: [
     [models_1.ReflectionKind.TypeParameter]: [ts.SyntaxKind.TypeParameter],
-    [models_1.ReflectionKind.Accessor]: [
-        ts.SyntaxKind.GetAccessor,
-        ts.SyntaxKind.SetAccessor,
-    ],
+    [models_1.ReflectionKind.Accessor]: [],
     [models_1.ReflectionKind.GetSignature]: [ts.SyntaxKind.GetAccessor],
@@ -144,2 +143,3 @@ [models_1.ReflectionKind.SetSignature]: [ts.SyntaxKind.SetAccessor],
     const comments = collectCommentRanges(ts.getLeadingCommentRanges(text, node.pos));
+    comments.reverse();
     const comment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
@@ -191,6 +191,29 @@ if (comment) {
 function declarationToCommentNode(node) {
-    if (node.parent?.kind === ts.SyntaxKind.VariableDeclarationList) {
+    if (!node.parent)
+        return node;
+    // const abc = 123
+    //       ^^^
+    if (node.parent.kind === ts.SyntaxKind.VariableDeclarationList) {
         return node.parent.parent;
     }
-    if (node.kind === ts.SyntaxKind.ModuleDeclaration) {
+    // const a = () => {}
+    //           ^^^^^^^^
+    if (node.parent.kind === ts.SyntaxKind.VariableDeclaration) {
+        return node.parent.parent.parent;
+    }
+    // class X { y = () => {} }
+    //               ^^^^^^^^
+    // function Z() {}
+    // Z.method = () => {}
+    //            ^^^^^^^^
+    // export default () => {}
+    //                ^^^^^^^^
+    if ([
+        ts.SyntaxKind.PropertyDeclaration,
+        ts.SyntaxKind.BinaryExpression,
+        ts.SyntaxKind.ExportAssignment,
+    ].includes(node.parent.kind)) {
+        return node.parent;
+    }
+    if (ts.isModuleDeclaration(node)) {
         if (!isTopmostModuleDeclaration(node)) {
@@ -206,9 +229,3 @@ return;
     }
-    if ([
-        ts.SyntaxKind.NamespaceExport,
-        ts.SyntaxKind.FunctionExpression,
-        ts.SyntaxKind.FunctionType,
-        ts.SyntaxKind.FunctionType,
-        ts.SyntaxKind.ArrowFunction,
-    ].includes(node.kind)) {
+    if ([ts.SyntaxKind.NamespaceExport, ts.SyntaxKind.FunctionType].includes(node.kind)) {
         return node.parent;
@@ -215,0 +232,0 @@ }

dist/lib/converter/comments/index.js

@@ -7,3 +7,2 @@ "use strict";
 const utils_1 = require("../../utils");
-const paths_1 = require("../../utils/paths");
 const blockLexer_1 = require("./blockLexer");
@@ -22,11 +21,9 @@ const discovery_1 = require("./discovery");
     }
-    const line = ts.getLineAndCharacterOfPosition(file, ranges[0].pos).line + 1;
-    const warning = (warning) => logger.warn(`${warning} in comment at ${(0, paths_1.nicePath)(file.fileName)}:${line}.`);
     let comment;
     switch (ranges[0].kind) {
         case ts.SyntaxKind.MultiLineCommentTrivia:
-            comment = (0, parser_1.parseComment)((0, blockLexer_1.lexBlockComment)(file.text, ranges[0].pos, ranges[0].end), config, warning);
+            comment = (0, parser_1.parseComment)((0, blockLexer_1.lexBlockComment)(file.text, ranges[0].pos, ranges[0].end), config, file, logger);
             break;
         case ts.SyntaxKind.SingleLineCommentTrivia:
-            comment = (0, parser_1.parseComment)((0, lineLexer_1.lexLineComments)(file.text, ranges), config, warning);
+            comment = (0, parser_1.parseComment)((0, lineLexer_1.lexLineComments)(file.text, ranges), config, file, logger);
             break;
@@ -33,0 +30,0 @@ default:

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

@@ -13,2 +13,3 @@ export declare enum TokenSyntaxKind {
     text: string;
+    pos: number;
 }

dist/lib/converter/comments/lineLexer.js

@@ -8,3 +8,3 @@ "use strict";
     let textToken;
-    for (const token of lexBlockComment2(file, ranges[0].pos, ranges[ranges.length - 1].end)) {
+    for (const token of lexLineComments2(file, ranges[0].pos, ranges[ranges.length - 1].end)) {
         if (token.kind === lexer_1.TokenSyntaxKind.Text) {
@@ -32,3 +32,3 @@ if (textToken) {
 exports.lexLineComments = lexLineComments;
-function* lexBlockComment2(file, pos, end) {
+function* lexLineComments2(file, pos, end) {
     // Trailing whitespace
@@ -89,2 +89,3 @@ while (pos < end && /\s/.test(file[end - 1])) {
                             text: codeText.join(""),
+                            pos,
                         };
@@ -121,2 +122,3 @@ pos = lookahead;
                             text: codeText.join(""),
+                            pos,
                         };
@@ -175,3 +177,2 @@ pos = lookahead;
                 }
-                pos = lookahead;
                 // This piece of text had line continuations or escaped text
@@ -181,3 +182,5 @@ yield {
                     text: textParts.join(""),
+                    pos,
                 };
+                pos = lookahead;
                 break;
@@ -193,2 +196,3 @@ }
             text: file.substring(start, pos),
+            pos: start,
         };
@@ -195,0 +199,0 @@ }

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

 import type { CommentParserConfig } from ".";
 import { Comment } from "../../models";
+import { Logger } from "../../utils";
+import type { MinimalSourceFile } from "../../utils/minimalSourceFile";
 import { Token } from "./lexer";
-export declare function parseComment(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, warning: (message: string) => void): Comment;
+export declare function parseComment(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger): Comment;

dist/lib/converter/comments/parser.js

@@ -7,30 +7,52 @@ "use strict";
 const utils_1 = require("../../utils");
+const paths_1 = require("../../utils/paths");
 const lexer_1 = require("./lexer");
 function makeLookaheadGenerator(gen) {
-    let nextItem = gen.next();
+    let trackHistory = false;
+    const history = [];
+    const next = [gen.next()];
     return {
         done() {
-            return !!nextItem.done;
+            return !!next[0].done;
         },
         peek() {
-            (0, assert_1.ok)(!nextItem.done);
-            return nextItem.value;
+            (0, assert_1.ok)(!next[0].done);
+            return next[0].value;
         },
         take() {
-            const thisItem = nextItem;
+            const thisItem = next.shift();
+            if (trackHistory) {
+                history.push(thisItem);
+            }
             (0, assert_1.ok)(!thisItem.done);
-            nextItem = gen.next();
+            next.push(gen.next());
             return thisItem.value;
         },
+        mark() {
+            (0, assert_1.ok)(!trackHistory, "Can only mark one location for backtracking at a time");
+            trackHistory = true;
+        },
+        release() {
+            trackHistory = false;
+            next.unshift(...history);
+            history.length = 0;
+        },
     };
 }
-function parseComment(tokens, config, warning) {
+function parseComment(tokens, config, file, logger) {
     const lexer = makeLookaheadGenerator(tokens);
+    const tok = lexer.done() || lexer.peek();
     const comment = new models_1.Comment();
-    comment.summary = blockContent(comment, lexer, config, warning);
+    comment.summary = blockContent(comment, lexer, config, warningImpl);
     while (!lexer.done()) {
-        comment.blockTags.push(blockTag(comment, lexer, config, warning));
+        comment.blockTags.push(blockTag(comment, lexer, config, warningImpl));
     }
-    postProcessComment(comment, warning);
+    postProcessComment(comment, (message) => {
+        (0, assert_1.ok)(typeof tok === "object");
+        logger.warn(`${message} in comment at ${(0, paths_1.nicePath)(file.fileName)}:${file.getLineAndCharacterOfPosition(tok.pos).line + 1}`);
+    });
     return comment;
+    function warningImpl(message, token) {
+        logger.warn(message, token.pos, file);
+    }
 }
@@ -81,33 +103,2 @@ exports.parseComment = parseComment;
         }
-        if (tag.tag === "@example" &&
-            !tag.content.some((part) => part.kind === "code")) {
-            const caption = tag.content[0].text.match(/^\s*<caption>(.*?)<\/caption>\s*(\n|$)/);
-            if (caption) {
-                const code = models_1.Comment.combineDisplayParts([
-                    {
-                        kind: "text",
-                        text: tag.content[0].text.slice(caption[0].length),
-                    },
-                    ...tag.content.slice(1),
-                ]);
-                tag.content = [
-                    {
-                        kind: "text",
-                        text: caption[1] + "\n",
-                    },
-                    {
-                        kind: "code",
-                        text: makeCodeBlock(code),
-                    },
-                ];
-            }
-            else {
-                tag.content = [
-                    {
-                        kind: "code",
-                        text: makeCodeBlock(models_1.Comment.combineDisplayParts(tag.content)),
-                    },
-                ];
-            }
-        }
     }
@@ -138,6 +129,55 @@ const remarks = comment.blockTags.filter((tag) => tag.tag === "@remarks");
     const blockTag = lexer.take();
-    (0, assert_1.ok)(blockTag.kind === lexer_1.TokenSyntaxKind.Tag); // blockContent is broken if this fails.
+    (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;
-    return new models_1.CommentTag(tagName, blockContent(comment, lexer, config, warning));
+    let content;
+    if (tagName === "@example") {
+        content = exampleBlockContent(comment, lexer, config, warning);
+    }
+    else {
+        content = blockContent(comment, lexer, config, warning);
+    }
+    return new models_1.CommentTag(tagName, content);
 }
+/**
+ * The `@example` tag gets a special case because otherwise we will produce many warnings
+ * about unescaped/mismatched/missing braces
+ */
+function exampleBlockContent(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")) {
+        return blockContent(comment, lexer, config, warning);
+    }
+    const tokens = [];
+    while ((lexer.done() || lexer.peek()) !== end) {
+        tokens.push(lexer.take());
+    }
+    const blockText = tokens
+        .map((tok) => tok.text)
+        .join("")
+        .trim();
+    const caption = blockText.match(/^\s*<caption>(.*?)<\/caption>\s*(\n|$)/);
+    if (caption) {
+        return [
+            {
+                kind: "text",
+                text: caption[1] + "\n",
+            },
+            {
+                kind: "code",
+                text: makeCodeBlock(blockText.slice(caption[0].length)),
+            },
+        ];
+    }
+    else {
+        return [
+            {
+                kind: "code",
+                text: makeCodeBlock(blockText),
+            },
+        ];
+    }
+}
 function blockContent(comment, lexer, config, warning) {
@@ -159,3 +199,3 @@ const content = [];
                 if (next.text === "@inheritdoc") {
-                    warning("The @inheritDoc tag should be properly capitalized");
+                    warning("The @inheritDoc tag should be properly capitalized", next);
                     next.text = "@inheritDoc";
@@ -170,3 +210,3 @@ }
                     comment.modifierTags.add(next.text);
-                    warning(`Treating unrecognized tag "${next.text}" as a modifier tag`);
+                    warning(`Treating unrecognized tag "${next.text}" as a modifier tag`, next);
                     break;
@@ -184,3 +224,3 @@ }
                 // Unmatched closing brace, generate a warning, and treat it as text.
-                warning(`Unmatched closing brace`);
+                warning(`Unmatched closing brace`, next);
                 content.push({ kind: "text", text: next.text });
@@ -233,3 +273,3 @@ break;
         ![lexer_1.TokenSyntaxKind.Text, lexer_1.TokenSyntaxKind.Tag].includes(lexer.peek().kind)) {
-        warning("Encountered an unescaped open brace without an inline tag");
+        warning("Encountered an unescaped open brace without an inline tag", openBrace);
         block.push({ kind: "text", text: openBrace.text });
@@ -243,3 +283,3 @@ return;
                 lexer.peek().kind != lexer_1.TokenSyntaxKind.Tag))) {
-        warning("Encountered an unescaped open brace without an inline tag");
+        warning("Encountered an unescaped open brace without an inline tag", openBrace);
         block.push({ kind: "text", text: openBrace.text + tagName.text });
@@ -252,3 +292,3 @@ return;
     if (!config.inlineTags.has(tagName.text)) {
-        warning(`Encountered an unknown inline tag "${tagName.text}"`);
+        warning(`Encountered an unknown inline tag "${tagName.text}"`, tagName);
     }
@@ -261,3 +301,3 @@ const content = [];
         if (token.kind === lexer_1.TokenSyntaxKind.OpenBrace) {
-            warning("Encountered an open brace within an inline tag, this is likely a mistake");
+            warning("Encountered an open brace within an inline tag, this is likely a mistake", token);
         }
@@ -267,3 +307,3 @@ content.push(token.kind === lexer_1.TokenSyntaxKind.NewLine ? " " : token.text);
     if (lexer.done()) {
-        warning("Inline tag is not closed");
+        warning("Inline tag is not closed", openBrace);
     }
@@ -270,0 +310,0 @@ else {

dist/lib/converter/comments/rawLexer.js

@@ -92,2 +92,3 @@ "use strict";
                             text: codeText.join(""),
+                            pos,
                         };
@@ -123,2 +124,3 @@ pos = lookahead;
                             text: codeText.join(""),
+                            pos,
                         };
@@ -177,3 +179,2 @@ pos = lookahead;
                 }
-                pos = lookahead;
                 // This piece of text had line continuations or escaped text
@@ -183,3 +184,5 @@ yield {
                     text: textParts.join(""),
+                    pos,
                 };
+                pos = lookahead;
                 break;
@@ -195,2 +198,3 @@ }
             text: file.substring(start, pos),
+            pos: start,
         };
@@ -197,0 +201,0 @@ }

dist/lib/converter/plugins/ImplementsPlugin.js

@@ -295,2 +295,10 @@ "use strict";
     }
+    else if (parent.kindOf(index_1.ReflectionKind.Property) &&
+        parent.type instanceof types_1.ReflectionType &&
+        parent.type.declaration.signatures &&
+        child.signatures) {
+        for (const [cs, ps] of (0, array_1.zip)(child.signatures, parent.type.declaration.signatures)) {
+            copyComment(cs, ps);
+        }
+    }
 }
@@ -297,0 +305,0 @@ /**

dist/lib/converter/plugins/InheritDocPlugin.js

@@ -73,2 +73,9 @@ "use strict";
             }
+            if (sourceRefl instanceof models_1.DeclarationReflection &&
+                sourceRefl.kindOf(models_1.ReflectionKind.Accessor)) {
+                // Accessors, like functions, never have comments on their actual root reflection.
+                // If the user didn't specify whether to inherit from the getter or setter, then implicitly
+                // try to inherit from the getter, #1968.
+                sourceRefl = sourceRefl.getSignature || sourceRefl.setSignature;
+            }
             if (!sourceRefl) {
@@ -75,0 +82,0 @@ this.application.logger.warn(`Failed to find "${source}" to inherit the comment from in the comment for ${reflection.getFullName()}`);

dist/lib/converter/plugins/PackagePlugin.js

@@ -19,2 +19,3 @@ "use strict";
 const parser_1 = require("../comments/parser");
+const minimalSourceFile_1 = require("../../utils/minimalSourceFile");
 /**
@@ -79,5 +80,3 @@ * A handler that tries to find the package.json and readme.md files of the
             const readme = (0, utils_1.readFile)(this.readmeFile);
-            const comment = (0, parser_1.parseComment)((0, rawLexer_1.lexCommentString)(readme), context.converter.config, (msg) => {
-                this.application.logger.warn(`${msg} in ${this.readmeFile}`);
-            });
+            const comment = (0, parser_1.parseComment)((0, rawLexer_1.lexCommentString)(readme), context.converter.config, new minimalSourceFile_1.MinimalSourceFile(readme, this.readmeFile), context.logger);
             if (comment.blockTags.length || comment.modifierTags.size) {
@@ -84,0 +83,0 @@ const ignored = [

dist/lib/converter/plugins/SourcePlugin.d.ts

@@ -9,2 +9,3 @@ import { ConverterComponent } from "../components";
     readonly gitRemote: string;
+    readonly basePath: string;
     /**
@@ -11,0 +12,0 @@ * All file names to find the base path from.

dist/lib/converter/plugins/SourcePlugin.js

@@ -88,3 +88,3 @@ "use strict";
             return;
-        const basePath = (0, fs_1.getCommonDirectory)([...this.fileNames]);
+        const basePath = this.basePath || (0, fs_1.getCommonDirectory)([...this.fileNames]);
         for (const refl of Object.values(context.project.reflections)) {
@@ -143,2 +143,5 @@ for (const source of refl.sources || []) {
 ], SourcePlugin.prototype, "gitRemote", void 0);
+__decorate([
+    (0, utils_1.BindOption)("basePath")
+], SourcePlugin.prototype, "basePath", void 0);
 SourcePlugin = __decorate([
@@ -145,0 +148,0 @@ (0, components_1.Component)({ name: "source" })

dist/lib/converter/symbols.js

@@ -344,8 +344,2 @@ "use strict";
         }
-        // Special case: "arrow properties" in type space should be treated as methods.
-        if (ts.isPropertySignature(declaration) &&
-            declaration.type &&
-            ts.isFunctionTypeNode(declaration.type)) {
-            return convertArrowAsMethod(context, symbol, declaration.type, exportSymbol);
-        }
     }
@@ -435,3 +429,3 @@ const reflection = context.createDeclarationReflection(context.scope.kindOf(models_1.ReflectionKind.Namespace)
     }
-    if (type.getCallSignatures().length && !type.getProperties().length) {
+    if (type.getCallSignatures().length) {
         return convertVariableAsFunction(context, symbol, exportSymbol);
@@ -438,0 +432,0 @@ }

dist/lib/models/types.d.ts

@@ -326,5 +326,4 @@ import type * as ts from "typescript";
      * This will usually be the same as `name`, unless namespaces are used.
-     * Will only be set for `ReferenceType`s pointing to a symbol within `node_modules`.
      */
-    qualifiedName?: string;
+    qualifiedName: string;
     /**
@@ -331,0 +330,0 @@ * The package that this type is referencing.

dist/lib/models/types.js

@@ -5,2 +5,3 @@ "use strict";
 const abstract_1 = require("./reflections/abstract");
+const tsutils_1 = require("../utils/tsutils");
 /**
@@ -632,3 +633,3 @@ * Base class of all type definitions.
 class ReferenceType extends Type {
-    constructor(name, target, project) {
+    constructor(name, target, project, qualifiedName) {
         super();
@@ -639,2 +640,3 @@ this.type = "reference";
         this._project = project;
+        this.qualifiedName = qualifiedName;
     }
@@ -666,6 +668,6 @@ /**
     static createResolvedReference(name, target, project) {
-        return new ReferenceType(name, target, project);
+        return new ReferenceType(name, target, project, name);
     }
     static createSymbolReference(symbol, context, name) {
-        const ref = new ReferenceType(name ?? symbol.name, symbol, context.project);
+        const ref = new ReferenceType(name ?? symbol.name, symbol, context.project, (0, tsutils_1.getQualifiedName)(context.checker, symbol));
         const symbolPath = symbol?.declarations?.[0]
@@ -687,13 +689,2 @@ ?.getSourceFile()
         ref.package = packageName;
-        const qualifiedName = context.checker.getFullyQualifiedName(symbol);
-        // I think this is less bad than depending on symbol.parent...
-        // https://github.com/microsoft/TypeScript/issues/38344
-        // It will break if someone names a directory with a quote in it, but so will lots
-        // of other things including other parts of TypeDoc. Until it *actually* breaks someone...
-        if (qualifiedName.startsWith('"')) {
-            ref.qualifiedName = qualifiedName.substring(qualifiedName.indexOf('".', 1) + 2);
-        }
-        else {
-            ref.qualifiedName = qualifiedName;
-        }
         return ref;
@@ -703,3 +694,3 @@ }
     static createBrokenReference(name, project) {
-        return new ReferenceType(name, -1, project);
+        return new ReferenceType(name, -1, project, name);
     }
@@ -728,3 +719,3 @@ getTypeString() {
         };
-        if (this.qualifiedName && this.package) {
+        if (this.package) {
             result.qualifiedName = this.qualifiedName;
@@ -731,0 +722,0 @@ result.package = this.package;

dist/lib/output/themes/default/layouts/default.js

@@ -5,3 +5,3 @@ "use strict";
 const utils_1 = require("../../../../utils");
-const defaultLayout = (context, props) => (utils_1.JSX.createElement("html", { class: "default" },
+const defaultLayout = (context, props) => (utils_1.JSX.createElement("html", { class: "default", lang: context.options.getValue("htmlLang") },
     utils_1.JSX.createElement("head", null,
@@ -8,0 +8,0 @@ utils_1.JSX.createElement("meta", { charSet: "utf-8" }),

dist/lib/serialization/schema.d.ts

@@ -122,4 +122,5 @@ /**
 }
-export interface ReferenceType extends Type, S<M.ReferenceType, "type" | "name" | "typeArguments" | "qualifiedName" | "package"> {
+export interface ReferenceType extends Type, S<M.ReferenceType, "type" | "name" | "typeArguments" | "package"> {
     id?: number;
+    qualifiedName?: string;
 }
@@ -126,0 +127,0 @@ export interface ReflectionType extends Type, S<M.ReflectionType, "type"> {

dist/lib/utils/entry-point.js

@@ -83,3 +83,3 @@ "use strict";
 function getEntryPointsForPaths(logger, inputFiles, options, programs = getEntryPrograms(logger, options)) {
-    const baseDir = (0, fs_1.getCommonDirectory)(inputFiles);
+    const baseDir = options.getValue("basePath") || (0, fs_1.getCommonDirectory)(inputFiles);
     const entryPoints = [];
@@ -86,0 +86,0 @@ entryLoop: for (const fileOrDir of inputFiles.map(fs_1.normalizePath)) {

dist/lib/utils/index.d.ts

@@ -20,1 +20,3 @@ export { filterMap, insertPrioritySorted, partition, removeIf, removeIfPresent, unique, } from "./array";
 export * as Validation from "./validation";
+export * from "./tsutils";
+export { MinimalSourceFile } from "./minimalSourceFile";

dist/lib/utils/index.js

@@ -17,3 +17,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validation = exports.renderElement = exports.Raw = exports.Fragment = exports.JSX = exports.EventHooks = exports.sortReflections = exports.loadPlugins = exports.discoverPlugins = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.DefaultMap = exports.LogLevel = exports.Logger = exports.ConsoleLogger = exports.CallbackLogger = exports.assertNever = exports.writeFileSync = exports.writeFile = exports.readFile = exports.normalizePath = exports.getCommonDirectory = exports.copySync = exports.copy = exports.EventDispatcher = exports.Event = exports.Component = exports.ChildableComponent = exports.AbstractComponent = exports.unique = exports.removeIfPresent = exports.removeIf = exports.partition = exports.insertPrioritySorted = exports.filterMap = void 0;
+exports.MinimalSourceFile = exports.Validation = exports.renderElement = exports.Raw = exports.Fragment = exports.JSX = exports.EventHooks = exports.sortReflections = exports.loadPlugins = exports.discoverPlugins = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.DefaultMap = exports.LogLevel = exports.Logger = exports.ConsoleLogger = exports.CallbackLogger = exports.assertNever = exports.writeFileSync = exports.writeFile = exports.readFile = exports.normalizePath = exports.getCommonDirectory = exports.copySync = exports.copy = exports.EventDispatcher = exports.Event = exports.Component = exports.ChildableComponent = exports.AbstractComponent = exports.unique = exports.removeIfPresent = exports.removeIf = exports.partition = exports.insertPrioritySorted = exports.filterMap = void 0;
 var array_1 = require("./array");
@@ -74,1 +74,4 @@ Object.defineProperty(exports, "filterMap", { enumerable: true, get: function () { return array_1.filterMap; } });
 exports.Validation = require("./validation");
+__exportStar(require("./tsutils"), exports);
+var minimalSourceFile_1 = require("./minimalSourceFile");
+Object.defineProperty(exports, "MinimalSourceFile", { enumerable: true, get: function () { return minimalSourceFile_1.MinimalSourceFile; } });

dist/lib/utils/loggers.d.ts

 import * as ts from "typescript";
+import type { MinimalSourceFile } from "./minimalSourceFile";
 /**
@@ -64,2 +65,3 @@ * List of known log levels. Used to specify the urgency of a log message.
     warn(text: string, node?: ts.Node): void;
+    warn(text: string, pos: number, file: MinimalSourceFile): void;
     /**
@@ -72,2 +74,3 @@ * Log the given error.
     error(text: string, node?: ts.Node): void;
+    error(text: string, pos: number, file: MinimalSourceFile): void;
     /** @internal */
@@ -80,5 +83,4 @@ deprecated(text: string, addStack?: boolean): void;
      * @param level The urgency of the log message.
-     * @param _node Optional node to be used to provide additional context about the message.
      */
-    log(_message: string, level: LogLevel, _node?: ts.Node): void;
+    log(_message: string, level: LogLevel): void;
     /**
@@ -96,2 +98,3 @@ * Print the given TypeScript log messages.
     diagnostic(diagnostic: ts.Diagnostic): void;
+    protected addContext(message: string, _level: LogLevel, ..._args: [ts.Node?] | [number, MinimalSourceFile]): string;
 }
@@ -112,3 +115,4 @@ /**
      */
-    log(message: string, level: LogLevel, node?: ts.Node): void;
+    log(message: string, level: LogLevel): void;
+    protected addContext(message: string, level: LogLevel, ...args: [ts.Node?] | [number, MinimalSourceFile]): string;
 }
@@ -115,0 +119,0 @@ /**

dist/lib/utils/loggers.js

@@ -38,19 +38,2 @@ "use strict";
 };
-function withContext(message, level, node) {
-    if (!node) {
-        return `${messagePrefixes[level]} ${message}`;
-    }
-    const file = node.getSourceFile();
-    const path = (0, paths_1.nicePath)(file.fileName);
-    const pos = node.getStart(file, false);
-    const { line, character } = ts.getLineAndCharacterOfPosition(file, pos);
-    const location = `${color(path, "cyan")}:${color(`${line + 1}`, "yellow")}:${color(`${character}`, "yellow")}`;
-    const start = file.text.lastIndexOf("\n", pos) + 1;
-    let end = file.text.indexOf("\n", start);
-    if (end === -1)
-        end = file.text.length;
-    const prefix = `${location} - ${messagePrefixes[level]}`;
-    const context = `${color(`${line + 1}`, "black")}    ${file.text.substring(start, end)}`;
-    return `${prefix} ${message}\n\n${context}\n`;
-}
 /**
@@ -118,25 +101,13 @@ * A logger that will not produce any output.
     }
-    /**
-     * Log the given warning.
-     *
-     * @param text  The warning that should be logged.
-     * @param args  The arguments that should be printed into the given warning.
-     */
-    warn(text, node) {
+    warn(text, ...args) {
         if (this.seenWarnings.has(text))
             return;
         this.seenWarnings.add(text);
-        this.log(text, LogLevel.Warn, node);
+        this.log(this.addContext(text, LogLevel.Warn, ...args), LogLevel.Warn);
     }
-    /**
-     * Log the given error.
-     *
-     * @param text  The error that should be logged.
-     * @param args  The arguments that should be printed into the given error.
-     */
-    error(text, node) {
+    error(text, ...args) {
         if (this.seenErrors.has(text))
             return;
         this.seenErrors.add(text);
-        this.log(text, LogLevel.Error, node);
+        this.log(this.addContext(text, LogLevel.Error, ...args), LogLevel.Error);
     }
@@ -158,5 +129,4 @@ /** @internal */
      * @param level The urgency of the log message.
-     * @param _node Optional node to be used to provide additional context about the message.
      */
-    log(_message, level, _node) {
+    log(_message, level) {
         if (level === LogLevel.Error) {
@@ -201,2 +171,5 @@ this.errorCount += 1;
     }
+    addContext(message, _level, ..._args) {
+        return message;
+    }
 }
@@ -220,3 +193,3 @@ exports.Logger = Logger;
      */
-    log(message, level, node) {
+    log(message, level) {
         super.log(message, level);
@@ -233,4 +206,23 @@ if (level < this.level && !isDebugging()) {
         // eslint-disable-next-line no-console
-        console[method](withContext(message, level, node));
+        console[method](message);
     }
+    addContext(message, level, ...args) {
+        if (typeof args[0] === "undefined") {
+            return `${messagePrefixes[level]} ${message}`;
+        }
+        if (typeof args[0] !== "number") {
+            return this.addContext(message, level, args[0].getStart(args[0].getSourceFile(), false), args[0].getSourceFile());
+        }
+        const [pos, file] = args;
+        const path = (0, paths_1.nicePath)(file.fileName);
+        const { line, character } = file.getLineAndCharacterOfPosition(pos);
+        const location = `${color(path, "cyan")}:${color(`${line + 1}`, "yellow")}:${color(`${character}`, "yellow")}`;
+        const start = file.text.lastIndexOf("\n", pos) + 1;
+        let end = file.text.indexOf("\n", start);
+        if (end === -1)
+            end = file.text.length;
+        const prefix = `${location} - ${messagePrefixes[level]}`;
+        const context = `${color(`${line + 1}`, "black")}    ${file.text.substring(start, end)}`;
+        return `${prefix} ${message}\n\n${context}\n`;
+    }
 }
@@ -237,0 +229,0 @@ exports.ConsoleLogger = ConsoleLogger;

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

@@ -58,2 +58,3 @@ import type { Theme as ShikiTheme } from "shiki";
     disableSources: boolean;
+    basePath: string;
     includes: string;
@@ -90,2 +91,3 @@ media: string;
     githubPages: boolean;
+    htmlLang: string;
     hideGenerator: boolean;
@@ -92,0 +94,0 @@ cleanOutputDir: boolean;

dist/lib/utils/options/sources/typedoc.js

@@ -192,2 +192,7 @@ "use strict";
     options.addDeclaration({
+        name: "basePath",
+        help: "Specifies the base path to be used when displaying file paths.",
+        type: declaration_1.ParameterType.Path,
+    });
+    options.addDeclaration({
         name: "excludeTags",
@@ -228,2 +233,8 @@ help: "Remove the listed block/modifier tags from doc comments.",
     options.addDeclaration({
+        name: "htmlLang",
+        help: "Sets the lang attribute in the generated html tag.",
+        type: declaration_1.ParameterType.String,
+        defaultValue: "en",
+    });
+    options.addDeclaration({
         name: "gaID",
@@ -230,0 +241,0 @@ help: "Set the Google Analytics tracking ID and activate tracking code.",

dist/lib/validation/documentation.d.ts

 import { ProjectReflection, ReflectionKind } from "../models";
-import { Logger } from "../utils";
+import type { Logger } from "../utils";
 export declare function validateDocumentation(project: ProjectReflection, logger: Logger, requiredToBeDocumented: readonly (keyof typeof ReflectionKind)[]): void;

dist/lib/validation/documentation.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateDocumentation = void 0;
-const path = require("path");
-const ts = require("typescript");
 const models_1 = require("../models");
-const utils_1 = require("../utils");
 const enum_1 = require("../utils/enum");
@@ -63,6 +60,3 @@ function validateDocumentation(project, logger, requiredToBeDocumented) {
             }
-            const { line } = ts.getLineAndCharacterOfPosition(sourceFile, decl.getStart());
-            const file = (0, utils_1.normalizePath)(path.relative(process.cwd(), sourceFile.fileName));
-            const loc = `${file}:${line + 1}`;
-            logger.warn(`${ref.getFriendlyFullName()}, defined at ${loc}, does not have any documentation.`);
+            logger.warn(`${ref.getFriendlyFullName()} does not have any documentation.`, decl);
         }
@@ -69,0 +63,0 @@ }

dist/lib/validation/exports.js

@@ -16,3 +16,3 @@ "use strict";
     return {
-        has(symbol) {
+        has(symbol, typeName) {
             // If it isn't declared anywhere, we can't produce a good error message about where
@@ -35,3 +35,3 @@ // the non-exported symbol is, so even if it isn't ignored, pretend it is. In practice,
             for (const [index, [file, name]] of processed.entries()) {
-                if (symbol.name === name &&
+                if (typeName === name &&
                     symbol.declarations.some((d) => d.getSourceFile().fileName.endsWith(file))) {
@@ -60,7 +60,7 @@ used.add(index);
                 if ((symbol.flags & ts.SymbolFlags.TypeParameter) === 0 &&
-                    !intentional.has(symbol) &&
+                    !intentional.has(symbol, type.qualifiedName) &&
                     !warned.has(symbol)) {
                     warned.add(symbol);
                     const decl = symbol.declarations[0];
-                    logger.warn(`${type.name} is referenced by ${current.getFullName()} but not included in the documentation.`, decl);
+                    logger.warn(`${type.qualifiedName} is referenced by ${current.getFullName()} but not included in the documentation.`, decl);
                 }
@@ -67,0 +67,0 @@ }

package.json

 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.23.2",
+  "version": "0.23.3",
   "homepage": "https://typedoc.org",
   "main": "./dist/index.js",
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./tsdoc.json": "./tsdoc.json"
   },
@@ -10,0 +11,0 @@ "types": "./dist/index.d.ts",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

992497

increased by0.61%

Number of package files

287

increased by1.41%

Lines of code

23481

increased by0.68%

No dependency changes