Improve link validation warning messages

Resolves #2967

Author: Gerrit0

CHANGELOG.md

@@ -13,6 +13,7 @@ title: Changelog
 - Attempting to highlight a supported language which is not enabled is now a warning, not an error, #2956.
 - Improved compatibility with CommonMark's link parsing, #2959.
 - Classes, variables, and functions exported with `export { type X }` are now detected and converted as interfaces/type aliases, #2962.
+- Improved warning messaging for links to symbols which were resolved, but the symbols were not included in the documentation, #2967.
 
 ## v0.28.5 (2025-05-26)
 

src/lib/internationalization/locales/en.cts

@@ -91,6 +91,8 @@ export = {
     inline_tag_not_closed: `Inline tag is not closed`,
 
     // validation
+    comment_for_0_links_to_1_not_included_in_docs_use_external_link_2:
+        `The comment for {0} links to "{1}" which was resolved but is not included in the documentation. To fix this warning export it or add {2} to the externalSymbolLinkMappings option`,
     failed_to_resolve_link_to_0_in_comment_for_1: `Failed to resolve link to "{0}" in comment for {1}`,
     failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2:
         `Failed to resolve link to "{0}" in comment for {1}. You may have wanted "{2}"`,

src/lib/validation/links.ts

@@ -2,6 +2,7 @@ import { i18n, type Logger } from "#utils";
 import {
     type Comment,
     type CommentDisplayPart,
+    type InlineTagDisplayPart,
     type ProjectReflection,
     type Reflection,
     ReflectionKind,
@@ -11,15 +12,15 @@ import {
 const linkTags = ["@link", "@linkcode", "@linkplain"];
 
 function getBrokenPartLinks(parts: readonly CommentDisplayPart[]) {
-    const links: string[] = [];
+    const links: InlineTagDisplayPart[] = [];
 
     for (const part of parts) {
         if (
             part.kind === "inline-tag" &&
             linkTags.includes(part.tag) &&
             (!part.target || part.target instanceof ReflectionSymbolId)
         ) {
-            links.push(part.text.trim());
+            links.push(part);
         }
     }
 
@@ -53,21 +54,22 @@ export function validateLinks(
 function checkReflection(reflection: Reflection, logger: Logger) {
     if (reflection.isProject() || reflection.isDeclaration()) {
         for (const broken of getBrokenPartLinks(reflection.readme || [])) {
+            const linkText = broken.text.trim();
             // #2360, "@" is a future reserved character in TSDoc component paths
             // If a link starts with it, and doesn't include a module source indicator "!"
             // then the user probably is trying to link to a package containing "@" with an absolute link.
-            if (broken.startsWith("@") && !broken.includes("!")) {
+            if (linkText.startsWith("@") && !linkText.includes("!")) {
                 logger.warn(
                     i18n.failed_to_resolve_link_to_0_in_readme_for_1_may_have_meant_2(
-                        broken,
+                        linkText,
                         reflection.getFriendlyFullName(),
-                        broken.replace(/[.#~]/, "!"),
+                        linkText.replace(/[.#~]/, "!"),
                     ),
                 );
             } else {
                 logger.warn(
                     i18n.failed_to_resolve_link_to_0_in_readme_for_1(
-                        broken,
+                        linkText,
                         reflection.getFriendlyFullName(),
                     ),
                 );
@@ -77,21 +79,19 @@ function checkReflection(reflection: Reflection, logger: Logger) {
 
     if (reflection.isDocument()) {
         for (const broken of getBrokenPartLinks(reflection.content)) {
-            // #2360, "@" is a future reserved character in TSDoc component paths
-            // If a link starts with it, and doesn't include a module source indicator "!"
-            // then the user probably is trying to link to a package containing "@" with an absolute link.
-            if (broken.startsWith("@") && !broken.includes("!")) {
+            const linkText = broken.text.trim();
+            if (linkText.startsWith("@") && !linkText.includes("!")) {
                 logger.warn(
                     i18n.failed_to_resolve_link_to_0_in_document_1_may_have_meant_2(
-                        broken,
+                        linkText,
                         reflection.getFriendlyFullName(),
-                        broken.replace(/[.#~]/, "!"),
+                        linkText.replace(/[.#~]/, "!"),
                     ),
                 );
             } else {
                 logger.warn(
                     i18n.failed_to_resolve_link_to_0_in_document_1(
-                        broken,
+                        linkText,
                         reflection.getFriendlyFullName(),
                     ),
                 );
@@ -100,25 +100,7 @@ function checkReflection(reflection: Reflection, logger: Logger) {
     }
 
     for (const broken of getBrokenLinks(reflection.comment)) {
-        // #2360, "@" is a future reserved character in TSDoc component paths
-        // If a link starts with it, and doesn't include a module source indicator "!"
-        // then the user probably is trying to link to a package containing "@" with an absolute link.
-        if (broken.startsWith("@") && !broken.includes("!")) {
-            logger.warn(
-                i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(
-                    broken,
-                    reflection.getFriendlyFullName(),
-                    broken.replace(/[.#~]/, "!"),
-                ),
-            );
-        } else {
-            logger.warn(
-                i18n.failed_to_resolve_link_to_0_in_comment_for_1(
-                    broken,
-                    reflection.getFriendlyFullName(),
-                ),
-            );
-        }
+        reportBrokenCommentLink(broken, reflection, logger);
     }
 
     if (
@@ -132,22 +114,35 @@ function checkReflection(reflection: Reflection, logger: Logger) {
                 getBrokenPartLinks,
             )
         ) {
-            if (broken.startsWith("@") && !broken.includes("!")) {
-                logger.warn(
-                    i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(
-                        broken,
-                        reflection.getFriendlyFullName(),
-                        broken.replace(/[.#~]/, "!"),
-                    ),
-                );
-            } else {
-                logger.warn(
-                    i18n.failed_to_resolve_link_to_0_in_comment_for_1(
-                        broken,
-                        reflection.getFriendlyFullName(),
-                    ),
-                );
-            }
+            reportBrokenCommentLink(broken, reflection, logger);
         }
     }
 }
+
+function reportBrokenCommentLink(broken: InlineTagDisplayPart, reflection: Reflection, logger: Logger) {
+    const linkText = broken.text.trim();
+    if (broken.target instanceof ReflectionSymbolId) {
+        logger.warn(
+            i18n.comment_for_0_links_to_1_not_included_in_docs_use_external_link_2(
+                reflection.getFriendlyFullName(),
+                linkText,
+                `{ "${broken.target.packageName}": { "${broken.target.qualifiedName}": "#" }}`,
+            ),
+        );
+    } else if (linkText.startsWith("@") && !linkText.includes("!")) {
+        logger.warn(
+            i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(
+                linkText,
+                reflection.getFriendlyFullName(),
+                linkText.replace(/[.#~]/, "!"),
+            ),
+        );
+    } else {
+        logger.warn(
+            i18n.failed_to_resolve_link_to_0_in_comment_for_1(
+                linkText,
+                reflection.getFriendlyFullName(),
+            ),
+        );
+    }
+}

src/test/behavior.c2.test.ts

@@ -887,6 +887,26 @@ describe("Behavior Tests", () => {
         ]);
     });
 
+    it("Handles links which do not resolve correctly", () => {
+        const project = convert("linkResolutionErrors");
+        app.options.setValue("validation", {
+            invalidLink: true,
+            notDocumented: false,
+            notExported: false,
+        });
+
+        app.validate(project);
+        logger.expectMessage(
+            'warn: The comment for abc links to "Map.size" which was resolved but is not included in the documentation. To fix this warning export it or add { "typescript": { "Map.size": "#" }} to the externalSymbolLinkMappings option',
+        );
+        logger.expectMessage(
+            'warn: Failed to resolve link to "DoesNotExist" in comment for abc',
+        );
+        logger.expectMessage(
+            'warn: Failed to resolve link to "@typedoc/foo.DoesNotExist" in comment for abc. You may have wanted "@typedoc/foo!DoesNotExist"',
+        );
+    });
+
     it("Handles merged declarations", () => {
         const project = convert("mergedDeclarations");
         const a = query(project, "SingleCommentMultiDeclaration");

src/test/converter2/behavior/linkResolutionErrors.ts

@@ -0,0 +1,6 @@
+/**
+ * {@link Map.size} TS resolves link, not included in docs #2700 #2967
+ * {@link DoesNotExist} Symbol does not exist #2681
+ * {@link @typedoc/foo.DoesNotExist} Symbol does not exist, looks like an attempt to link to a package directly #2360
+ */
+export const abc = new Map<string, number>();

src/test/converter2/issues/gh2681.ts

@@ -9,7 +9,6 @@ import {
     QueryType,
     ReferenceReflection,
     ReflectionKind,
-    ReflectionSymbolId,
     ReflectionType,
     SignatureReflection,
     UnionType,
@@ -1671,16 +1670,6 @@ describe("Issue Tests", () => {
         logger.expectNoOtherMessages();
     });
 
-    it("#2681 reports warnings on @link tags which resolve to a type not included in the documentation", () => {
-        const project = convert();
-        app.options.setValue("validation", false);
-        app.options.setValue("validation", { invalidLink: true });
-        app.validate(project);
-        logger.expectMessage(
-            'warn: Failed to resolve link to "Generator" in comment for bug',
-        );
-    });
-
     it("#2683 supports @param on parameters with functions", () => {
         const project = convert();
         const action = querySig(project, "action");
@@ -1733,31 +1722,7 @@ describe("Issue Tests", () => {
         );
     });
 
-    it("#2700a correctly parses links to global properties", () => {
-        const project = convert();
-        app.options.setValue("validation", {
-            invalidLink: true,
-            notDocumented: false,
-            notExported: false,
-        });
-
-        app.validate(project);
-        logger.expectMessage(
-            'warn: Failed to resolve link to "Map.size | size user specified" in comment for abc',
-        );
-        logger.expectMessage(
-            'warn: Failed to resolve link to "Map.size user specified" in comment for abc',
-        );
-        logger.expectMessage(
-            'warn: Failed to resolve link to "Map.size" in comment for abc',
-        );
-
-        const abc = query(project, "abc");
-        const link = abc.comment?.summary.find((c) => c.kind === "inline-tag");
-        ok(link?.target instanceof ReflectionSymbolId);
-    });
-
-    it("#2700b respects user specified link text when resolving external links", () => {
+    it("#2700 respects user specified link text when resolving external links", () => {
         const project = convert();
 
         const abc = query(project, "abc");