CHANGELOG.md

@@ -1,5 +1,25 @@
 # Unreleased
 
+## v0.23.26 (2023-02-26)
+
+### Features
+
+-   Added `Application.EVENT_VALIDATE_PROJECT` event for plugins which implement custom validation, #2183.
+-   Plugins may now return an object from external symbol resolvers, #2066.
+-   Expose `Comment.displayPartsToMarkdown` on for themes overwriting the `comment` helper, #2115.
+
+### Bug Fixes
+
+-   Fix crash when converting `export default undefined`, #2175.
+-   Fix error in console when clicking on headings in the readme, #2170.
+-   TypeDoc will now ignore parameters of callback parameters when validating that all parameters have documentation, #2154.
+
+### Thanks!
+
+-   @captain-torch
+-   @loopingz
+-   @RebeccaStevens
+
 ## v0.23.25 (2023-02-11)
 
 ### Breaking Changes

internal-docs/third-party-symbols.md

@@ -96,3 +96,58 @@ export function load(app: Application) {
     });
 }
 ```
+
+Since TypeDoc 0.23.26, plugins may also return return an object for more control
+over the displayed link. The returned `caption` will be used if the user does not
+specify the link text.
+
+```ts
+import { Application, type DeclarationReference } from "typedoc";
+
+const documentedExports = [
+    "chunk",
+    "compact",
+    "concat",
+    "difference",
+    "differenceBy",
+    "differenceWith",
+];
+
+export function load(app: Application) {
+    app.converter.addUnknownSymbolResolver((ref: DeclarationReference) => {
+        if (
+            // TS defined symbols
+            ref.moduleSource !== "@types/lodash" &&
+            // User {@link} tags
+            ref.moduleSource !== "lodash"
+        ) {
+            return;
+        }
+
+        // If someone did {@link lodash!}, link them directly to the home page.
+        if (!ref.symbolReference) {
+            return "https://lodash.com/";
+        }
+
+        if (!ref.symbolReference.path) {
+            // Someone included a meaning, but not a path.
+            // https://typedoc.org/guides/declaration-references/#meaning
+            return;
+        }
+
+        if (ref.symbolReference.path.length === 1) {
+            const name = ref.symbolReference.path[0].path;
+            if (documentedExports.includes(name)) {
+                return {
+                    target: `https://lodash.com/docs/4.17.15#${name}`,
+                    caption: name,
+                };
+            }
+        }
+    });
+}
+```
+
+The unknown symbol resolver will also be passed the reflection containing the link
+and, if the link was defined by the user, the [CommentDisplayPart](https://typedoc.org/api/types/CommentDisplayPart.html)
+which was parsed into the `DeclarationReference` provided as the first argument.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.23.25",
+  "version": "0.23.26",
   "homepage": "https://typedoc.org",
   "main": "./dist/index.js",
   "exports": {
@@ -27,7 +27,7 @@
   "dependencies": {
     "lunr": "^2.3.9",
     "marked": "^4.2.12",
-    "minimatch": "^6.1.6",
+    "minimatch": "^7.1.3",
     "shiki": "^0.14.1"
   },
   "peerDependencies": {

src/index.ts

@@ -13,6 +13,8 @@ export {
     type ComponentPath,
     type Meaning,
     type MeaningKeyword,
+    type ExternalResolveResult,
+    type ExternalSymbolResolver,
 } from "./lib/converter";
 
 export {

src/lib/application-events.ts

@@ -1,3 +1,4 @@
 export const ApplicationEvents = {
     BOOTSTRAP_END: "bootstrapEnd",
+    VALIDATE_PROJECT: "validateProject",
 };

src/lib/application.ts

@@ -107,6 +107,12 @@ export class Application extends ChildableComponent<
      */
     static readonly EVENT_BOOTSTRAP_END = ApplicationEvents.BOOTSTRAP_END;
 
+    /**
+     * Emitted when validation is being run.
+     * The listener will be given an instance of {@link ProjectReflection}.
+     */
+    static readonly EVENT_VALIDATE_PROJECT = ApplicationEvents.VALIDATE_PROJECT;
+
     /**
      * Create a new TypeDoc application instance.
      */
@@ -431,6 +437,8 @@ export class Application extends ChildableComponent<
             validateLinks(project, this.logger);
         }
 
+        this.trigger(Application.EVENT_VALIDATE_PROJECT, project);
+
         this.logger.verbose(`Validation took ${Date.now() - start}ms`);
     }
 

src/lib/converter/comments/index.ts

@@ -103,13 +103,14 @@ export function getComment(
     logger: Logger,
     commentStyle: CommentStyle
 ): Comment | undefined {
+    const declarations = symbol.declarations || [];
+
     if (
-        symbol
-            .getDeclarations()
-            ?.every((d) => jsDocCommentKinds.includes(d.kind))
+        declarations.length &&
+        declarations.every((d) => jsDocCommentKinds.includes(d.kind))
     ) {
         return getJsDocComment(
-            symbol.declarations![0] as ts.JSDocPropertyLikeTag,
+            declarations[0] as ts.JSDocPropertyLikeTag,
             config,
             logger
         );
@@ -119,7 +120,7 @@ export function getComment(
         discoverComment(symbol, kind, logger, commentStyle),
         config,
         logger,
-        symbol.declarations?.some(ts.isSourceFile) || false
+        declarations.some(ts.isSourceFile)
     );
 
     if (!comment && kind === ReflectionKind.Property) {

src/lib/converter/comments/linkResolver.ts

@@ -16,12 +16,19 @@ import { resolveDeclarationReference } from "./declarationReferenceResolver";
 const urlPrefix = /^(http|ftp)s?:\/\//;
 const brackets = /\[\[(?!include:)([^\]]+)\]\]/g;
 
+export type ExternalResolveResult = { target: string; caption?: string };
+export type ExternalSymbolResolver = (
+    ref: DeclarationReference,
+    refl: Reflection,
+    part: Readonly<CommentDisplayPart> | undefined
+) => ExternalResolveResult | string | undefined;
+
 export function resolveLinks(
     comment: Comment,
     reflection: Reflection,
     validation: ValidationOptions,
     logger: Logger,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined
+    externalResolver: ExternalSymbolResolver
 ) {
     let warned = false;
     const warn = () => {
@@ -39,7 +46,7 @@ export function resolveLinks(
         warn,
         validation,
         logger,
-        attemptExternalResolve
+        externalResolver
     );
     for (const tag of comment.blockTags) {
         tag.content = resolvePartLinks(
@@ -48,7 +55,7 @@ export function resolveLinks(
             warn,
             validation,
             logger,
-            attemptExternalResolve
+            externalResolver
         );
     }
 
@@ -59,7 +66,7 @@ export function resolveLinks(
             warn,
             validation,
             logger,
-            attemptExternalResolve
+            externalResolver
         );
     }
 }
@@ -70,7 +77,7 @@ export function resolvePartLinks(
     warn: () => void,
     validation: ValidationOptions,
     logger: Logger,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined
+    externalResolver: ExternalSymbolResolver
 ): CommentDisplayPart[] {
     return parts.flatMap((part) =>
         processPart(
@@ -79,7 +86,7 @@ export function resolvePartLinks(
             warn,
             validation,
             logger,
-            attemptExternalResolve
+            externalResolver
         )
     );
 }
@@ -90,7 +97,7 @@ function processPart(
     warn: () => void,
     validation: ValidationOptions,
     logger: Logger,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined
+    externalResolver: ExternalSymbolResolver
 ): CommentDisplayPart | CommentDisplayPart[] {
     if (part.kind === "text" && brackets.test(part.text)) {
         warn();
@@ -106,7 +113,7 @@ function processPart(
             return resolveLinkTag(
                 reflection,
                 part,
-                attemptExternalResolve,
+                externalResolver,
                 (msg: string) => {
                     if (validation.invalidLink) {
                         logger.warn(msg);
@@ -122,7 +129,7 @@ function processPart(
 function resolveLinkTag(
     reflection: Reflection,
     part: InlineTagDisplayPart,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined,
+    externalResolver: ExternalSymbolResolver,
     warn: (message: string) => void
 ) {
     let pos = 0;
@@ -136,7 +143,7 @@ function resolveLinkTag(
     const declRef = parseDeclarationReference(part.text, pos, end);
 
     let target: Reflection | string | undefined;
-    let defaultDisplayText: string;
+    let defaultDisplayText = "";
     if (declRef) {
         // Got one, great! Try to resolve the link
         target = resolveDeclarationReference(reflection, declRef[0]);
@@ -146,9 +153,22 @@ function resolveLinkTag(
             defaultDisplayText = target.name;
         } else {
             // If we didn't find a link, it might be a @link tag to an external symbol, check that next.
-            target = attemptExternalResolve(declRef[0]);
-            if (target) {
-                defaultDisplayText = part.text.substring(0, pos);
+            const externalResolveResult = externalResolver(
+                declRef[0],
+                reflection,
+                part
+            );
+
+            defaultDisplayText = part.text.substring(0, pos);
+
+            switch (typeof externalResolveResult) {
+                case "string":
+                    target = externalResolveResult;
+                    break;
+                case "object":
+                    target = externalResolveResult.target;
+                    defaultDisplayText =
+                        externalResolveResult.caption || defaultDisplayText;
             }
         }
     }
@@ -185,7 +205,8 @@ function resolveLinkTag(
     }
 
     part.target = target;
-    part.text = part.text.substring(pos).trim() || defaultDisplayText!;
+    part.text =
+        part.text.substring(pos).trim() || defaultDisplayText || part.text;
 
     return part;
 }