More control delegated for external link resolvers

src/index.ts

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

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 ExternalResolveAttempt = (
+    ref: DeclarationReference,
+    part: CommentDisplayPart,
+    refl: Reflection
+) => ExternalResolveResult | string | undefined;
+
 export function resolveLinks(
     comment: Comment,
     reflection: Reflection,
     validation: ValidationOptions,
     logger: Logger,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined
+    attemptExternalResolve: ExternalResolveAttempt
 ) {
     let warned = false;
     const warn = () => {
@@ -70,7 +77,7 @@ export function resolvePartLinks(
     warn: () => void,
     validation: ValidationOptions,
     logger: Logger,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined
+    attemptExternalResolve: ExternalResolveAttempt
 ): CommentDisplayPart[] {
     return parts.flatMap((part) =>
         processPart(
@@ -90,7 +97,7 @@ function processPart(
     warn: () => void,
     validation: ValidationOptions,
     logger: Logger,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined
+    attemptExternalResolve: ExternalResolveAttempt
 ): CommentDisplayPart | CommentDisplayPart[] {
     if (part.kind === "text" && brackets.test(part.text)) {
         warn();
@@ -122,7 +129,7 @@ function processPart(
 function resolveLinkTag(
     reflection: Reflection,
     part: InlineTagDisplayPart,
-    attemptExternalResolve: (ref: DeclarationReference) => string | undefined,
+    attemptExternalResolve: ExternalResolveAttempt,
     warn: (message: string) => void
 ) {
     let pos = 0;
@@ -146,9 +153,23 @@ 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);
+            let externalResolveResult = attemptExternalResolve(
+                declRef[0],
+                part,
+                reflection
+            );
+
+            switch (typeof externalResolveResult) {
+                case "string":
+                    target = externalResolveResult as string;
+                    defaultDisplayText = part.text.substring(0, pos);
+                    break;
+                case "object":
+                    externalResolveResult =
+                        externalResolveResult as ExternalResolveResult;
+                    part.target = externalResolveResult.target;
+                    part.text = externalResolveResult.caption;
+                    return part;
             }
         }
     }

src/lib/converter/converter.ts

@@ -78,7 +78,11 @@ export class Converter extends ChildableComponent<
 
     private _config?: CommentParserConfig;
     private _externalSymbolResolvers: Array<
-        (ref: DeclarationReference) => string | undefined
+        (
+            ref: DeclarationReference,
+            part?: CommentDisplayPart,
+            refl?: Reflection
+        ) => string | undefined
     > = [];
 
     get config(): CommentParserConfig {
@@ -274,9 +278,13 @@ export class Converter extends ChildableComponent<
     }
 
     /** @internal */
-    resolveExternalLink(ref: DeclarationReference): string | undefined {
+    resolveExternalLink(
+        ref: DeclarationReference,
+        part?: CommentDisplayPart,
+        refl?: Reflection
+    ): string | undefined {
         for (const resolver of this._externalSymbolResolvers) {
-            const resolved = resolver(ref);
+            const resolved = resolver(ref, part, refl);
             if (resolved) return resolved;
         }
     }
@@ -296,7 +304,7 @@ export class Converter extends ChildableComponent<
                 owner,
                 this.validation,
                 this.owner.logger,
-                (ref) => this.resolveExternalLink(ref)
+                (ref, part, refl) => this.resolveExternalLink(ref, part, refl)
             );
         } else {
             let warned = false;
@@ -315,7 +323,7 @@ export class Converter extends ChildableComponent<
                 warn,
                 this.validation,
                 this.owner.logger,
-                (ref) => this.resolveExternalLink(ref)
+                (ref, part, refl) => this.resolveExternalLink(ref, part, refl)
             );
         }
     }

src/lib/converter/index.ts

@@ -9,5 +9,9 @@ export type {
     Meaning,
     MeaningKeyword,
 } from "./comments/declarationReference";
+export type {
+    ExternalResolveAttempt,
+    ExternalResolveResult,
+} from "./comments/linkResolver";
 
 import "./plugins/index";