typedoc 0.22.16 → 0.23.0-beta.2

package/README.md

@@ -79,23 +79,17 @@ For a complete list of the command line arguments run `typedoc --help` or visit
     Specifies the location the documentation should be written to. Defaults to `./docs`
 -   `--json <path/to/output.json>`<br>
     Specifies the location and file name a json file describing the project is
-    written to. When specified no documentation will be generated.
+    written to. When specified no documentation will be generated unless `--out` is also
+    specified.
 -   `--options`<br>
     Specify a json option file that should be loaded. If not specified TypeDoc
     will look for 'typedoc.json' in the current directory.
 -   `--tsconfig <path/to/tsconfig.json>`<br>
     Specify a typescript config file that should be loaded. If not
     specified TypeDoc will look for 'tsconfig.json' in the current directory.
-
-#### Source file handling
-
 -   `--exclude <pattern>`<br>
     Exclude files by the given pattern when a path is provided as source.
     Supports standard minimatch patterns.
--   `--excludeNotDocumented`<br>
-    Only document items which have a doc comment. This option is useful, if you
-    want to document only small part of your symbols and do not show the
-    remaining ones in the documentation.
 
 #### Theming
 
@@ -109,8 +103,6 @@ For a complete list of the command line arguments run `typedoc --help` or visit
 
 #### Miscellaneous
 
--   `--listInvalidSymbolLinks`<br>
-    Display the list of links that don't point to actual code symbols.
 -   `--version`<br>
     Display the version number of TypeDoc.
 -   `--help`<br>
@@ -123,9 +115,3 @@ You can find TypeDoc on GitHub; feel free to open an issue or create a pull requ
 https://github.com/TypeStrong/typedoc
 
 For more information, read the [contribution guide](https://github.com/TypeStrong/typedoc/blob/master/.github/CONTRIBUTING.md).
-
-## License
-
-Copyright (c) 2015 [Sebastian Lenz](https://typedoc.org).<br>
-Copyright (c) 2016-2021 [TypeDoc Contributors](https://github.com/TypeStrong/typedoc/graphs/contributors).<br>
-Licensed under the Apache License 2.0.

package/dist/index.d.ts

@@ -3,13 +3,13 @@ export { EventDispatcher, Event } from "./lib/utils/events";
 export { resetReflectionID } from "./lib/models/reflections/abstract";
 export { normalizePath } from "./lib/utils/fs";
 export * from "./lib/models";
-export { Converter, Context } from "./lib/converter";
+export { Converter, Context, type CommentParserConfig } from "./lib/converter";
 export { Renderer, DefaultTheme, DefaultThemeRenderContext, UrlMapping, Theme, PageEvent, RendererEvent, MarkdownEvent, } from "./lib/output";
 export type { RenderTemplate, RendererHooks } from "./lib/output";
 export { ArgumentsReader, BindOption, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, } from "./lib/utils";
-export type { OptionsReader, TypeDocOptions, TypeDocOptionMap, ValidationOptions, TypeDocOptionValues, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, } 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";
 export type { EventMap, EventCallback } from "./lib/utils/events";
-export { JSONOutput, Serializer, SerializerComponent, SerializeEvent, } from "./lib/serialization";
+export { JSONOutput, Serializer, type SerializerComponent, SerializeEvent, } from "./lib/serialization";
 export type { SerializeEventData } from "./lib/serialization";
 import * as TypeScript from "typescript";
 export { TypeScript };

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeScript = exports.SerializeEvent = exports.SerializerComponent = 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.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.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = 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");
 Object.defineProperty(exports, "Application", { enumerable: true, get: function () { return application_1.Application; } });
 var events_1 = require("./lib/utils/events");
@@ -53,7 +53,6 @@ Object.defineProperty(exports, "EventHooks", { enumerable: true, get: function (
 var serialization_1 = require("./lib/serialization");
 Object.defineProperty(exports, "JSONOutput", { enumerable: true, get: function () { return serialization_1.JSONOutput; } });
 Object.defineProperty(exports, "Serializer", { enumerable: true, get: function () { return serialization_1.Serializer; } });
-Object.defineProperty(exports, "SerializerComponent", { enumerable: true, get: function () { return serialization_1.SerializerComponent; } });
 Object.defineProperty(exports, "SerializeEvent", { enumerable: true, get: function () { return serialization_1.SerializeEvent; } });
 const TypeScript = require("typescript");
 exports.TypeScript = TypeScript;

package/dist/lib/application.js

@@ -17,12 +17,13 @@ const index_2 = require("./utils/index");
 const component_1 = require("./utils/component");
 const utils_1 = require("./utils");
 const array_1 = require("./utils/array");
-const exports_1 = require("./validation/exports");
 const assert_1 = require("assert");
 const entry_point_1 = require("./utils/entry-point");
 const paths_1 = require("./utils/paths");
 const general_1 = require("./utils/general");
+const exports_1 = require("./validation/exports");
 const documentation_1 = require("./validation/documentation");
+const links_1 = require("./validation/links");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const packageInfo = require("../../package.json");
 const supportedVersionMajorMinor = packageInfo.peerDependencies.typescript
@@ -142,13 +143,12 @@ let Application = Application_1 = class Application extends component_1.Childabl
         }
         const programs = (0, array_1.unique)(entryPoints.map((e) => e.program));
         this.logger.verbose(`Converting with ${programs.length} programs ${entryPoints.length} entry points`);
-        const errors = (0, array_1.flatMap)([...programs], ts.getPreEmitDiagnostics);
+        const errors = programs.flatMap((program) => ts.getPreEmitDiagnostics(program));
         if (errors.length) {
             this.logger.diagnostics(errors);
             return;
         }
-        if (this.options.getValue("emit") === "both" ||
-            this.options.getValue("emit") === true) {
+        if (this.options.getValue("emit") === "both") {
             for (const program of programs) {
                 program.emit();
             }
@@ -160,11 +160,10 @@ let Application = Application_1 = class Application extends component_1.Childabl
         return project;
     }
     convertAndWatch(success) {
-        var _a, _b, _c;
         this.options.freeze();
         if (!this.options.getValue("preserveWatchOutput") &&
             this.logger instanceof index_2.ConsoleLogger) {
-            (_b = (_a = ts.sys).clearScreen) === null || _b === void 0 ? void 0 : _b.call(_a);
+            ts.sys.clearScreen?.();
         }
         this.logger.verbose(`Using TypeScript ${this.getTypeScriptVersion()} from ${this.getTypeScriptPath()}`);
         if (!supportedVersionMajorMinor.some((version) => version == ts.versionMajorMinor)) {
@@ -185,17 +184,17 @@ let Application = Application_1 = class Application extends component_1.Childabl
             this.logger.error("The packages option of entryPointStrategy is not supported in watch mode.");
             return;
         }
-        const tsconfigFile = (_c = index_2.TSConfigReader.findConfigFile(this.options.getValue("tsconfig"))) !== null && _c !== void 0 ? _c : "tsconfig.json";
+        const tsconfigFile = index_2.TSConfigReader.findConfigFile(this.options.getValue("tsconfig")) ??
+            "tsconfig.json";
         // We don't want to do it the first time to preserve initial debug status messages. They'll be lost
         // after the user saves a file, but better than nothing...
         let firstStatusReport = true;
         const host = ts.createWatchCompilerHost(tsconfigFile, {}, ts.sys, ts.createEmitAndSemanticDiagnosticsBuilderProgram, (diagnostic) => this.logger.diagnostic(diagnostic), (status, newLine, _options, errorCount) => {
-            var _a, _b;
             if (!firstStatusReport &&
                 errorCount === void 0 &&
                 !this.options.getValue("preserveWatchOutput") &&
                 this.logger instanceof index_2.ConsoleLogger) {
-                (_b = (_a = ts.sys).clearScreen) === null || _b === void 0 ? void 0 : _b.call(_a);
+                ts.sys.clearScreen?.();
             }
             firstStatusReport = false;
             this.logger.info(ts.flattenDiagnosticMessageText(status.messageText, newLine));
@@ -207,8 +206,7 @@ let Application = Application_1 = class Application extends component_1.Childabl
                 return;
             }
             if (successFinished) {
-                if (this.options.getValue("emit") === "both" ||
-                    this.options.getValue("emit") === true) {
+                if (this.options.getValue("emit") === "both") {
                     currentProgram.emit();
                 }
                 this.logger.resetErrors();
@@ -240,21 +238,23 @@ let Application = Application_1 = class Application extends component_1.Childabl
                 currentProgram = program.getProgram();
                 runSuccess();
             }
-            origAfterProgramCreate === null || origAfterProgramCreate === void 0 ? void 0 : origAfterProgramCreate(program);
+            origAfterProgramCreate?.(program);
         };
         ts.createWatchProgram(host);
     }
     validate(project) {
         const checks = this.options.getValue("validation");
+        const start = Date.now();
         if (checks.notExported) {
             (0, exports_1.validateExports)(project, this.logger, this.options.getValue("intentionallyNotExported"));
         }
         if (checks.notDocumented) {
             (0, documentation_1.validateDocumentation)(project, this.logger, this.options.getValue("requiredToBeDocumented"));
         }
-        // checks.invalidLink is currently handled when rendering by the MarkedLinksPlugin.
-        // It should really move here, but I'm putting that off until done refactoring the comment
-        // parsing so that we don't have duplicate parse logic all over the place.
+        if (checks.invalidLink) {
+            (0, links_1.validateLinks)(project, this.logger);
+        }
+        this.logger.verbose(`Validation took ${Date.now() - start}ms`);
     }
     /**
      * Render HTML for the given project

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

@@ -0,0 +1,2 @@
+import { Token } from "./lexer";
+export declare function lexBlockComment(file: string, pos?: number, end?: number): Generator<Token, undefined, undefined>;

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

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lexBlockComment = void 0;
+const lexer_1 = require("./lexer");
+function* lexBlockComment(file, pos = 0, end = file.length) {
+    // Wrapper around our real lex function to collapse adjacent text tokens.
+    let textToken;
+    for (const token of lexBlockComment2(file, pos, end)) {
+        if (token.kind === lexer_1.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;
+}
+exports.lexBlockComment = lexBlockComment;
+function* lexBlockComment2(file, pos, end) {
+    pos += 2; // Leading '/*'
+    end -= 2; // Trailing '*/'
+    if (pos < end && file[pos] === "*") {
+        // Might start with '/**'
+        pos++;
+    }
+    // Before skipping whitespace, figure out the comment indent size
+    const [commentHasStars, indent] = discoverIndent(file, pos, end);
+    // Skip leading whitespace
+    while (pos < end && /\s/.test(file[pos])) {
+        pos++;
+    }
+    // Trailing whitespace
+    while (pos < end && /\s/.test(file[end - 1])) {
+        end--;
+    }
+    let lineStart = true;
+    let braceStartsType = false;
+    for (;;) {
+        if (pos >= end) {
+            return;
+        }
+        if (lineStart) {
+            pos = skipIndent(pos);
+            if (commentHasStars && file[pos] === "*") {
+                pos++;
+                if (file[pos] === " ") {
+                    pos++;
+                }
+            }
+            lineStart = false;
+        }
+        switch (file[pos]) {
+            case "\n":
+                yield makeToken(lexer_1.TokenSyntaxKind.NewLine, 1);
+                lineStart = true;
+                break;
+            case "{":
+                if (braceStartsType && nextNonWs(pos + 1) !== "@") {
+                    yield makeToken(lexer_1.TokenSyntaxKind.TypeAnnotation, findEndOfType(pos) - pos);
+                    braceStartsType = false;
+                }
+                else {
+                    yield makeToken(lexer_1.TokenSyntaxKind.OpenBrace, 1);
+                }
+                break;
+            case "}":
+                yield makeToken(lexer_1.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;
+                while (lookahead + 1 < end && file[lookahead + 1] === "`") {
+                    tickCount++;
+                    lookahead++;
+                }
+                let lookaheadStart = pos;
+                const codeText = [];
+                lookahead++;
+                while (lookahead < end) {
+                    if (lookaheadExactlyNTicks(lookahead, tickCount)) {
+                        lookahead += tickCount;
+                        codeText.push(file.substring(lookaheadStart, lookahead));
+                        yield {
+                            kind: lexer_1.TokenSyntaxKind.Code,
+                            text: codeText.join(""),
+                        };
+                        pos = lookahead;
+                        break;
+                    }
+                    else if (file[lookahead] === "`") {
+                        while (lookahead < end && file[lookahead] === "`") {
+                            lookahead++;
+                        }
+                    }
+                    else if (file[lookahead] === "\\" &&
+                        lookahead + 1 < end &&
+                        file[lookahead + 1] === "/") {
+                        codeText.push(file.substring(lookaheadStart, lookahead));
+                        lookaheadStart = lookahead + 1;
+                        lookahead += 2;
+                    }
+                    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 = skipIndent(lookahead);
+                        if (commentHasStars && file[lookahead] === "*") {
+                            lookahead++;
+                            if (file[lookahead] === " ") {
+                                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: lexer_1.TokenSyntaxKind.Code,
+                            text: codeText.join(""),
+                        };
+                        pos = lookahead;
+                    }
+                    else {
+                        yield makeToken(lexer_1.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) {
+                    braceStartsType = true;
+                    yield makeToken(lexer_1.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;
+                }
+                pos = lookahead;
+                // This piece of text had line continuations or escaped text
+                yield {
+                    kind: lexer_1.TokenSyntaxKind.Text,
+                    text: textParts.join(""),
+                };
+                break;
+            }
+        }
+    }
+    function makeToken(kind, size) {
+        const start = pos;
+        pos += size;
+        return {
+            kind,
+            text: file.substring(start, pos),
+        };
+    }
+    function skipIndent(pos) {
+        let taken = indent;
+        let lookahead = pos;
+        while (taken > 0 &&
+            lookahead < end &&
+            file[lookahead] !== "\n" &&
+            /\s/.test(file[lookahead])) {
+            taken--;
+            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];
+    }
+}
+function discoverIndent(file, pos, end) {
+    let indent = 0;
+    while (pos < end && file[pos] !== "\n") {
+        pos++;
+    }
+    outer: while (pos < end) {
+        pos++;
+        const lineStart = pos;
+        while (pos < end && file[pos] !== "\n") {
+            if (/\S/.test(file[pos])) {
+                indent = pos - lineStart;
+                break outer;
+            }
+            pos++;
+        }
+    }
+    const commentHasStars = pos < end && file[pos] === "*";
+    return [commentHasStars, indent];
+}

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

@@ -0,0 +1,5 @@
+import * as ts from "typescript";
+import { ReflectionKind } from "../../models";
+import type { Logger } from "../../utils";
+export declare function discoverComment(symbol: ts.Symbol, kind: ReflectionKind, logger: Logger): [ts.SourceFile, ts.CommentRange] | undefined;
+export declare function discoverSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): [ts.SourceFile, ts.CommentRange] | undefined;