typedoc 0.24.0-beta.2 → 0.24.0-beta.4

package/README.md

@@ -19,7 +19,7 @@ npm install typedoc --save-dev
 
 ## Usage
 
-To generate documentation TypeDoc needs to know your project entry point, and TypeScript
+To generate documentation TypeDoc needs to know your project entry point and TypeScript
 compiler options. It will automatically try to find your `tsconfig.json` file, so you can
 just specify the entry point of your library:
 
@@ -38,37 +38,10 @@ By default, TypeDoc will search for a file called `index` under the directory.
 
 ### Monorepos / Workspaces
 
-If your codebase is comprised of one or more npm packages, you can pass the paths to these
-packages and TypeDoc will attempt to determine entry points based on `package.json`'s `main`
-property (with default value `index.js`) and if it wasn't found, based on `types` property.
-If any of the packages given are the root of an [npm Workspace](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
-or a [Yarn Workspace](https://classic.yarnpkg.com/en/docs/workspaces/) TypeDoc will find all
-the `workspaces` defined in the `package.json`. In order to find your entry points, TypeDoc requires
-either that you turn on sourcemaps so that it can discover the original TS file, or that you
-specify `"typedocMain": "src/index.ts"` to explicitly state where the package entry point is.
-Supports wildcard paths in the same fashion as those found in npm or Yarn workspaces.
-
-#### Single npm module
-
-```bash
-typedoc --entryPointStrategy packages .
-```
-
-#### Monorepo with npm/Yarn workspace at the root
-
-```bash
-typedoc --entryPointStrategy packages .
-```
-
-#### Monorepo with manually specified sub-packages to document
-
-This can be useful if you do not want all your workspaces to be processed.
-Accepts the same paths as would go in the `package.json`'s workspaces
-
-```bash
-# Note the single quotes prevent shell wildcard expansion, allowing typedoc to do the expansion
-typedoc --entryPointStrategy packages a-package 'some-more-packages/*' 'some-other-packages/*'
-```
+If your codebase is comprised of one or more npm packages, you can build documentation for each of them individually
+and merge the results together into a single site by setting `entryPointStrategy` to `packages`. In this mode TypeDoc
+requires configuration to be present in each directory to specify the entry points. For an example setup, see
+https://github.com/Gerrit0/typedoc-packages-example
 
 ### Arguments
 

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export * from "./lib/models";
 export { Converter, Context, type CommentParserConfig, type DeclarationReference, type SymbolReference, type ComponentPath, type Meaning, type MeaningKeyword, type ExternalResolveResult, type ExternalSymbolResolver, } from "./lib/converter";
 export { Renderer, DefaultTheme, DefaultThemeRenderContext, UrlMapping, Theme, PageEvent, RendererEvent, MarkdownEvent, IndexEvent, } from "./lib/output";
 export type { RenderTemplate, RendererHooks } from "./lib/output";
-export { ArgumentsReader, BindOption, CommentStyle, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, MinimalSourceFile, } from "./lib/utils";
+export { ArgumentsReader, BindOption, CommentStyle, JSX, LogLevel, Logger, Options, PackageJsonReader, 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, ObjectDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, ManuallyValidatedOption, EnumKeys, } from "./lib/utils";
 export type { EventMap, EventCallback } from "./lib/utils/events";
 export { JSONOutput, Serializer, Deserializer, type Deserializable, type DeserializerComponent, type SerializerComponent, SerializeEvent, } from "./lib/serialization";

package/dist/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeScript = exports.SerializeEvent = exports.Deserializer = 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.IndexEvent = 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.Deserializer = exports.Serializer = exports.JSONOutput = exports.MinimalSourceFile = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.PackageJsonReader = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.IndexEvent = 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");
@@ -49,6 +49,7 @@ Object.defineProperty(exports, "JSX", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return utils_1.LogLevel; } });
 Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return utils_1.Logger; } });
 Object.defineProperty(exports, "Options", { enumerable: true, get: function () { return utils_1.Options; } });
+Object.defineProperty(exports, "PackageJsonReader", { enumerable: true, get: function () { return utils_1.PackageJsonReader; } });
 Object.defineProperty(exports, "ParameterHint", { enumerable: true, get: function () { return utils_1.ParameterHint; } });
 Object.defineProperty(exports, "ParameterType", { enumerable: true, get: function () { return utils_1.ParameterType; } });
 Object.defineProperty(exports, "TSConfigReader", { enumerable: true, get: function () { return utils_1.TSConfigReader; } });

package/dist/lib/cli.js

@@ -36,6 +36,7 @@ const td = __importStar(require("typedoc"));
 const app = new td.Application();
 app.options.addReader(new td.ArgumentsReader(0));
 app.options.addReader(new td.TypeDocReader());
+app.options.addReader(new td.PackageJsonReader());
 app.options.addReader(new td.TSConfigReader());
 app.options.addReader(new td.ArgumentsReader(300));
 void run(app)
@@ -74,17 +75,13 @@ async function run(app) {
     }
     if (app.options.getValue("watch")) {
         app.convertAndWatch(async (project) => {
-            const out = app.options.getValue("out");
-            if (out) {
-                await app.generateDocs(project, out);
-            }
             const json = app.options.getValue("json");
+            if (!json || app.options.isSet("out")) {
+                await app.generateDocs(project, app.options.getValue("out"));
+            }
             if (json) {
                 await app.generateJson(project, json);
             }
-            if (!out && !json) {
-                await app.generateDocs(project, "./docs");
-            }
         });
         return ExitCodes.Ok;
     }
@@ -96,26 +93,25 @@ async function run(app) {
         app.logger.hasWarnings()) {
         return ExitCodes.CompileError;
     }
+    const preValidationWarnCount = app.logger.warningCount;
     app.validate(project);
+    const hadValidationWarnings = app.logger.warningCount !== preValidationWarnCount;
     if (app.logger.hasErrors()) {
         return ExitCodes.ValidationError;
     }
-    if (app.options.getValue("treatWarningsAsErrors") &&
-        app.logger.hasWarnings()) {
+    if (hadValidationWarnings &&
+        (app.options.getValue("treatWarningsAsErrors") ||
+            app.options.getValue("treatValidationWarningsAsErrors"))) {
         return ExitCodes.ValidationError;
     }
     if (app.options.getValue("emit") !== "none") {
-        const out = app.options.getValue("out");
-        if (out) {
-            await app.generateDocs(project, out);
-        }
         const json = app.options.getValue("json");
+        if (!json || app.options.isSet("out")) {
+            await app.generateDocs(project, app.options.getValue("out"));
+        }
         if (json) {
             await app.generateJson(project, json);
         }
-        if (!out && !json) {
-            await app.generateDocs(project, "./docs");
-        }
         if (app.logger.hasErrors()) {
             return ExitCodes.OutputError;
         }

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

@@ -1,2 +1,3 @@
+import ts from "typescript";
 import { Token } from "./lexer";
-export declare function lexBlockComment(file: string, pos?: number, end?: number): Generator<Token, undefined, undefined>;
+export declare function lexBlockComment(file: string, pos?: number, end?: number, jsDoc?: ts.JSDoc | undefined, checker?: ts.TypeChecker | undefined): Generator<Token, undefined, undefined>;

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

@@ -1,11 +1,17 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lexBlockComment = void 0;
+const typescript_1 = __importDefault(require("typescript"));
 const lexer_1 = require("./lexer");
-function* lexBlockComment(file, pos = 0, end = file.length) {
+const ReflectionSymbolId_1 = require("../../models/reflections/ReflectionSymbolId");
+const symbols_1 = require("../utils/symbols");
+function* lexBlockComment(file, pos = 0, end = file.length, jsDoc = undefined, checker = undefined) {
     // Wrapper around our real lex function to collapse adjacent text tokens.
     let textToken;
-    for (const token of lexBlockComment2(file, pos, end)) {
+    for (const token of lexBlockComment2(file, pos, end, getLinkTags(jsDoc), checker)) {
         if (token.kind === lexer_1.TokenSyntaxKind.Text) {
             if (textToken) {
                 textToken.text += token.text;
@@ -28,7 +34,21 @@ function* lexBlockComment(file, pos = 0, end = file.length) {
     return;
 }
 exports.lexBlockComment = lexBlockComment;
-function* lexBlockComment2(file, pos, end) {
+function getLinkTags(jsDoc) {
+    const result = [];
+    if (!jsDoc || typeof jsDoc.comment !== "object")
+        return result;
+    for (const part of jsDoc.comment) {
+        switch (part.kind) {
+            case typescript_1.default.SyntaxKind.JSDocLink:
+            case typescript_1.default.SyntaxKind.JSDocLinkCode:
+            case typescript_1.default.SyntaxKind.JSDocLinkPlain:
+                result.push(part);
+        }
+    }
+    return result;
+}
+function* lexBlockComment2(file, pos, end, linkTags, checker) {
     pos += 2; // Leading '/*'
     end -= 2; // Trailing '*/'
     if (pos < end && file[pos] === "*") {
@@ -47,6 +67,7 @@ function* lexBlockComment2(file, pos, end) {
     }
     let lineStart = true;
     let braceStartsType = false;
+    let linkTagIndex = 0;
     for (;;) {
         if (pos >= end) {
             return;
@@ -171,7 +192,9 @@ function* lexBlockComment2(file, pos, end) {
                 if (lookahead !== pos + 1 &&
                     (lookahead === end || /\s/.test(file[lookahead]))) {
                     braceStartsType = true;
-                    yield makeToken(lexer_1.TokenSyntaxKind.Tag, lookahead - pos);
+                    const token = makeToken(lexer_1.TokenSyntaxKind.Tag, lookahead - pos);
+                    attachLinkTagResult(token);
+                    yield token;
                     break;
                 }
             }
@@ -213,6 +236,24 @@ function* lexBlockComment2(file, pos, end) {
             }
         }
     }
+    function attachLinkTagResult(token) {
+        // We might need to skip link tags if someone has link tags inside of an example comment
+        // pos-1 for opening brace, TS doesn't allow spaces between opening brace and @ sign as of 5.0.2
+        while (linkTagIndex < linkTags.length &&
+            linkTags[linkTagIndex].pos < token.pos - 1) {
+            linkTagIndex++;
+        }
+        if (linkTagIndex < linkTags.length &&
+            linkTags[linkTagIndex].pos === token.pos - 1) {
+            const link = linkTags[linkTagIndex];
+            if (link.name) {
+                const tsTarget = checker?.getSymbolAtLocation(link.name);
+                if (tsTarget) {
+                    token.linkTarget = new ReflectionSymbolId_1.ReflectionSymbolId((0, symbols_1.resolveAliasedSymbol)(tsTarget, checker));
+                }
+            }
+        }
+    }
     function makeToken(kind, size) {
         const start = pos;
         pos += size;

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

@@ -2,5 +2,10 @@ import ts from "typescript";
 import { ReflectionKind } from "../../models";
 import { Logger } from "../../utils";
 import { CommentStyle } from "../../utils/options/declaration";
-export declare function discoverComment(symbol: ts.Symbol, kind: ReflectionKind, logger: Logger, commentStyle: CommentStyle): [ts.SourceFile, ts.CommentRange[]] | undefined;
-export declare function discoverSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, commentStyle: CommentStyle): [ts.SourceFile, ts.CommentRange[]] | undefined;
+export interface DiscoveredComment {
+    file: ts.SourceFile;
+    ranges: ts.CommentRange[];
+    jsDoc: ts.JSDoc | undefined;
+}
+export declare function discoverComment(symbol: ts.Symbol, kind: ReflectionKind, logger: Logger, commentStyle: CommentStyle): DiscoveredComment | undefined;
+export declare function discoverSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, commentStyle: CommentStyle): DiscoveredComment | undefined;

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

@@ -9,6 +9,7 @@ const models_1 = require("../../models");
 const utils_1 = require("../../utils");
 const declaration_1 = require("../../utils/options/declaration");
 const paths_1 = require("../../utils/paths");
+const assert_1 = require("assert");
 // Note: This does NOT include JSDoc syntax kinds. This is important!
 // Comments from @typedef and @callback tags are handled specially by
 // the JSDoc converter because we only want part of the comment when
@@ -120,7 +121,11 @@ function discoverComment(symbol, kind, logger, commentStyle) {
             }
             const selectedDocComment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
             if (selectedDocComment) {
-                discovered.push([decl.getSourceFile(), selectedDocComment]);
+                discovered.push({
+                    file: decl.getSourceFile(),
+                    ranges: selectedDocComment,
+                    jsDoc: findJsDocForComment(node, selectedDocComment),
+                });
             }
         }
     }
@@ -131,9 +136,9 @@ function discoverComment(symbol, kind, logger, commentStyle) {
             return discovered[0];
         default: {
             logger.warn(`${symbol.name} has multiple declarations with a comment. An arbitrary comment will be used.`);
-            const locations = discovered.map(([sf, [{ pos }]]) => {
-                const path = (0, paths_1.nicePath)(sf.fileName);
-                const line = typescript_1.default.getLineAndCharacterOfPosition(sf, pos).line + 1;
+            const locations = discovered.map(({ file, ranges: [{ pos }] }) => {
+                const path = (0, paths_1.nicePath)(file.fileName);
+                const line = typescript_1.default.getLineAndCharacterOfPosition(file, pos).line + 1;
                 return `${path}:${line}`;
             });
             logger.info(`The comments for ${symbol.name} are declared at:\n\t${locations.join("\n\t")}`);
@@ -147,15 +152,42 @@ function discoverSignatureComment(declaration, commentStyle) {
     if (!node) {
         return;
     }
+    if (typescript_1.default.isJSDocSignature(node)) {
+        const comment = node.parent.parent;
+        (0, assert_1.ok)(typescript_1.default.isJSDoc(comment));
+        return {
+            file: node.getSourceFile(),
+            ranges: [
+                {
+                    kind: typescript_1.default.SyntaxKind.MultiLineCommentTrivia,
+                    pos: comment.pos,
+                    end: comment.end,
+                },
+            ],
+            jsDoc: undefined,
+        };
+    }
     const text = node.getSourceFile().text;
     const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
     comments.reverse();
     const comment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
     if (comment) {
-        return [node.getSourceFile(), comment];
+        return {
+            file: node.getSourceFile(),
+            ranges: comment,
+            jsDoc: findJsDocForComment(node, comment),
+        };
     }
 }
 exports.discoverSignatureComment = discoverSignatureComment;
+function findJsDocForComment(node, ranges) {
+    if (ranges[0].kind === typescript_1.default.SyntaxKind.MultiLineCommentTrivia) {
+        const jsDocs = typescript_1.default
+            .getJSDocCommentsAndTags(node)
+            .map((doc) => typescript_1.default.findAncestor(doc, typescript_1.default.isJSDoc));
+        return jsDocs.find((doc) => doc.pos === ranges[0].pos);
+    }
+}
 /**
  * Check whether the given module declaration is the topmost.
  *

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

@@ -7,6 +7,6 @@ export interface CommentParserConfig {
     inlineTags: Set<string>;
     modifierTags: Set<string>;
 }
-export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle): Comment | undefined;
-export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle): Comment | undefined;
-export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger): Comment | undefined;
+export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker): Comment | undefined;
+export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker): Comment | undefined;
+export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker): Comment | undefined;

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

@@ -19,10 +19,10 @@ const jsDocCommentKinds = [
     typescript_1.default.SyntaxKind.JSDocEnumTag,
 ];
 const commentCache = new WeakMap();
-function getCommentWithCache(discovered, config, logger) {
+function getCommentWithCache(discovered, config, logger, checker) {
     if (!discovered)
         return;
-    const [file, ranges] = discovered;
+    const { file, ranges, jsDoc } = discovered;
     const cache = commentCache.get(file) || new Map();
     if (cache?.has(ranges[0].pos)) {
         return cache.get(ranges[0].pos).clone();
@@ -30,7 +30,7 @@ function getCommentWithCache(discovered, config, logger) {
     let comment;
     switch (ranges[0].kind) {
         case typescript_1.default.SyntaxKind.MultiLineCommentTrivia:
-            comment = (0, parser_1.parseComment)((0, blockLexer_1.lexBlockComment)(file.text, ranges[0].pos, ranges[0].end), config, file, logger);
+            comment = (0, parser_1.parseComment)((0, blockLexer_1.lexBlockComment)(file.text, ranges[0].pos, ranges[0].end, jsDoc, checker), config, file, logger);
             break;
         case typescript_1.default.SyntaxKind.SingleLineCommentTrivia:
             comment = (0, parser_1.parseComment)((0, lineLexer_1.lexLineComments)(file.text, ranges), config, file, logger);
@@ -42,8 +42,8 @@ function getCommentWithCache(discovered, config, logger) {
     commentCache.set(file, cache);
     return comment.clone();
 }
-function getCommentImpl(commentSource, config, logger, moduleComment) {
-    const comment = getCommentWithCache(commentSource, config, logger);
+function getCommentImpl(commentSource, config, logger, moduleComment, checker) {
+    const comment = getCommentWithCache(commentSource, config, logger, checker);
     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.
@@ -61,35 +61,35 @@ function getCommentImpl(commentSource, config, logger, moduleComment) {
     }
     return comment;
 }
-function getComment(symbol, kind, config, logger, commentStyle) {
+function getComment(symbol, kind, config, logger, commentStyle, checker) {
     const declarations = symbol.declarations || [];
     if (declarations.length &&
         declarations.every((d) => jsDocCommentKinds.includes(d.kind))) {
-        return getJsDocComment(declarations[0], config, logger);
+        return getJsDocComment(declarations[0], config, logger, checker);
     }
-    const comment = getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, commentStyle), config, logger, declarations.some(typescript_1.default.isSourceFile));
+    const comment = getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, commentStyle), config, logger, declarations.some(typescript_1.default.isSourceFile), checker);
     if (!comment && kind === models_1.ReflectionKind.Property) {
-        return getConstructorParamPropertyComment(symbol, config, logger, commentStyle);
+        return getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker);
     }
     return comment;
 }
 exports.getComment = getComment;
-function getConstructorParamPropertyComment(symbol, config, logger, commentStyle) {
+function getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker) {
     const decl = symbol.declarations?.find(typescript_1.default.isParameter);
     if (!decl)
         return;
     const ctor = decl.parent;
-    const comment = getSignatureComment(ctor, config, logger, commentStyle);
+    const comment = getSignatureComment(ctor, config, logger, commentStyle, checker);
     const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
     if (paramTag) {
         return new models_1.Comment(paramTag.content);
     }
 }
-function getSignatureComment(declaration, config, logger, commentStyle) {
-    return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, commentStyle), config, logger, false);
+function getSignatureComment(declaration, config, logger, commentStyle, checker) {
+    return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, commentStyle), config, logger, false, checker);
 }
 exports.getSignatureComment = getSignatureComment;
-function getJsDocComment(declaration, config, logger) {
+function getJsDocComment(declaration, config, logger, checker) {
     const file = declaration.getSourceFile();
     // First, get the whole comment. We know we'll need all of it.
     let parent = declaration.parent;
@@ -97,16 +97,17 @@ function getJsDocComment(declaration, config, logger) {
         parent = parent.parent;
     }
     // Then parse it.
-    const comment = getCommentWithCache([
+    const comment = getCommentWithCache({
         file,
-        [
+        ranges: [
             {
                 kind: typescript_1.default.SyntaxKind.MultiLineCommentTrivia,
                 pos: parent.pos,
                 end: parent.end,
             },
         ],
-    ], config, logger);
+        jsDoc: parent,
+    }, config, logger, checker);
     // And pull out the tag we actually care about.
     if (typescript_1.default.isJSDocEnumTag(declaration)) {
         return new models_1.Comment(comment.getTag("@enum")?.content);

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

@@ -1,3 +1,4 @@
+import type { ReflectionSymbolId } from "../../models";
 export declare enum TokenSyntaxKind {
     Text = "text",
     NewLine = "new_line",
@@ -11,4 +12,5 @@ export interface Token {
     kind: TokenSyntaxKind;
     text: string;
     pos: number;
+    linkTarget?: ReflectionSymbolId;
 }

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

@@ -5,5 +5,5 @@ export type ExternalResolveResult = {
     caption?: string;
 };
 export type ExternalSymbolResolver = (ref: DeclarationReference, refl: Reflection, part: Readonly<CommentDisplayPart> | undefined) => ExternalResolveResult | string | undefined;
-export declare function resolveLinks(comment: Comment, reflection: Reflection, externalResolver: ExternalSymbolResolver): void;
-export declare function resolvePartLinks(reflection: Reflection, parts: readonly CommentDisplayPart[], externalResolver: ExternalSymbolResolver): CommentDisplayPart[];
+export declare function resolveLinks(comment: Comment, reflection: Reflection, externalResolver: ExternalSymbolResolver, useTsResolution: boolean): void;
+export declare function resolvePartLinks(reflection: Reflection, parts: readonly CommentDisplayPart[], externalResolver: ExternalSymbolResolver, useTsResolution: boolean): CommentDisplayPart[];

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

@@ -9,40 +9,48 @@ const models_1 = require("../../models");
 const declarationReference_1 = require("./declarationReference");
 const declarationReferenceResolver_1 = require("./declarationReferenceResolver");
 const urlPrefix = /^(http|ftp)s?:\/\//;
-function resolveLinks(comment, reflection, externalResolver) {
-    comment.summary = resolvePartLinks(reflection, comment.summary, externalResolver);
+function resolveLinks(comment, reflection, externalResolver, useTsResolution) {
+    comment.summary = resolvePartLinks(reflection, comment.summary, externalResolver, useTsResolution);
     for (const tag of comment.blockTags) {
-        tag.content = resolvePartLinks(reflection, tag.content, externalResolver);
+        tag.content = resolvePartLinks(reflection, tag.content, externalResolver, useTsResolution);
     }
     if (reflection instanceof models_1.DeclarationReflection && reflection.readme) {
-        reflection.readme = resolvePartLinks(reflection, reflection.readme, externalResolver);
+        reflection.readme = resolvePartLinks(reflection, reflection.readme, externalResolver, useTsResolution);
     }
 }
 exports.resolveLinks = resolveLinks;
-function resolvePartLinks(reflection, parts, externalResolver) {
-    return parts.flatMap((part) => processPart(reflection, part, externalResolver));
+function resolvePartLinks(reflection, parts, externalResolver, useTsResolution) {
+    return parts.flatMap((part) => processPart(reflection, part, externalResolver, useTsResolution));
 }
 exports.resolvePartLinks = resolvePartLinks;
-function processPart(reflection, part, externalResolver) {
+function processPart(reflection, part, externalResolver, useTsResolution) {
     if (part.kind === "inline-tag") {
         if (part.tag === "@link" ||
             part.tag === "@linkcode" ||
             part.tag === "@linkplain") {
-            return resolveLinkTag(reflection, part, externalResolver);
+            return resolveLinkTag(reflection, part, externalResolver, useTsResolution);
         }
     }
     return part;
 }
-function resolveLinkTag(reflection, part, externalResolver) {
+function resolveLinkTag(reflection, part, externalResolver, useTsResolution) {
+    let defaultDisplayText = "";
     let pos = 0;
     const end = part.text.length;
     while (pos < end && typescript_1.default.isWhiteSpaceLike(part.text.charCodeAt(pos))) {
         pos++;
     }
-    // Try to parse one
-    const declRef = (0, declarationReference_1.parseDeclarationReference)(part.text, pos, end);
     let target;
-    let defaultDisplayText = "";
+    if (useTsResolution && part.target instanceof models_1.ReflectionSymbolId) {
+        target = reflection.project.getReflectionFromSymbolId(part.target);
+        if (target) {
+            pos = end;
+            defaultDisplayText =
+                part.text.replace(/^\s*[A-Z_$][\w$]*[ |]*/i, "") || target.name;
+        }
+    }
+    // Try to parse a declaration reference if we didn't use the TS symbol for resolution
+    const declRef = !target && (0, declarationReference_1.parseDeclarationReference)(part.text, pos, end);
     if (declRef) {
         // Got one, great! Try to resolve the link
         target = (0, declarationReferenceResolver_1.resolveDeclarationReference)(reflection, declRef[0]);
@@ -65,14 +73,11 @@ function resolveLinkTag(reflection, part, externalResolver) {
             }
         }
     }
-    if (!target) {
-        if (urlPrefix.test(part.text)) {
-            const wsIndex = part.text.search(/\s/);
-            target =
-                wsIndex === -1 ? part.text : part.text.substring(0, wsIndex);
-            pos = target.length;
-            defaultDisplayText = target;
-        }
+    if (!target && urlPrefix.test(part.text)) {
+        const wsIndex = part.text.search(/\s/);
+        target = wsIndex === -1 ? part.text : part.text.substring(0, wsIndex);
+        pos = target.length;
+        defaultDisplayText = target;
     }
     // Remaining text after an optional pipe is the link text, so advance
     // until that's consumed.

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

@@ -299,9 +299,13 @@ function inlineTag(lexer, block, config, warning) {
     else {
         lexer.take(); // Close brace
     }
-    block.push({
+    const inlineTag = {
         kind: "inline-tag",
         tag: tagName.text,
         text: content.join(""),
-    });
+    };
+    if (tagName.linkTarget) {
+        inlineTag.target = tagName.linkTarget;
+    }
+    block.push(inlineTag);
 }

package/dist/lib/converter/context.d.ts

@@ -46,7 +46,7 @@ export declare class Context {
      */
     constructor(converter: Converter, programs: readonly ts.Program[], project: ProjectReflection, scope?: Context["scope"]);
     /** @internal */
-    get logger(): import("../utils/loggers").Logger;
+    get logger(): import("../utils").Logger;
     /**
      * Return the compiler options.
      */

package/dist/lib/converter/context.js

@@ -120,10 +120,10 @@ class Context {
         if (exportSymbol &&
             reflection.kind &
                 (index_1.ReflectionKind.SomeModule | index_1.ReflectionKind.Reference)) {
-            reflection.comment = (0, comments_1.getComment)(exportSymbol, reflection.kind, this.converter.config, this.logger, this.converter.commentStyle);
+            reflection.comment = (0, comments_1.getComment)(exportSymbol, reflection.kind, this.converter.config, this.logger, this.converter.commentStyle, this.checker);
         }
         if (symbol && !reflection.comment) {
-            reflection.comment = (0, comments_1.getComment)(symbol, reflection.kind, this.converter.config, this.logger, this.converter.commentStyle);
+            reflection.comment = (0, comments_1.getComment)(symbol, reflection.kind, this.converter.config, this.logger, this.converter.commentStyle, this.checker);
         }
         if (this.shouldBeStatic) {
             reflection.setFlag(index_1.ReflectionFlag.Static);

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

@@ -32,6 +32,8 @@ export declare class Converter extends ChildableComponent<Application, Converter
     validation: ValidationOptions;
     /** @internal */
     externalSymbolLinkMappings: Record<string, Record<string, string>>;
+    /** @internal */
+    useTsLinkResolution: boolean;
     private _config?;
     private _externalSymbolResolvers;
     get config(): CommentParserConfig;

package/dist/lib/converter/converter.js

@@ -123,10 +123,10 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
     }
     resolveLinks(comment, owner) {
         if (comment instanceof index_1.Comment) {
-            (0, linkResolver_1.resolveLinks)(comment, owner, (ref, part, refl) => this.resolveExternalLink(ref, part, refl));
+            (0, linkResolver_1.resolveLinks)(comment, owner, (ref, part, refl) => this.resolveExternalLink(ref, part, refl), this.useTsLinkResolution);
         }
         else {
-            return (0, linkResolver_1.resolvePartLinks)(owner, comment, (ref, part, refl) => this.resolveExternalLink(ref, part, refl));
+            return (0, linkResolver_1.resolvePartLinks)(owner, comment, (ref, part, refl) => this.resolveExternalLink(ref, part, refl), this.useTsLinkResolution);
         }
     }
     /**
@@ -166,7 +166,7 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
             context.project.registerReflection(context.project, symbol);
             context.project.comment =
                 symbol &&
-                    (0, comments_1.getComment)(symbol, context.project.kind, this.config, this.application.logger, this.commentStyle);
+                    (0, comments_1.getComment)(symbol, context.project.kind, this.config, this.application.logger, this.commentStyle, context.checker);
             context.trigger(Converter_1.EVENT_CREATE_DECLARATION, context.project);
             moduleContext = context;
         }
@@ -334,6 +334,9 @@ __decorate([
 __decorate([
     (0, utils_1.BindOption)("externalSymbolLinkMappings")
 ], Converter.prototype, "externalSymbolLinkMappings", void 0);
+__decorate([
+    (0, utils_1.BindOption)("useTsLinkResolution")
+], Converter.prototype, "useTsLinkResolution", void 0);
 Converter = Converter_1 = __decorate([
     (0, component_1.Component)({
         name: "converter",