From f41f6c8f578c8c60a02a0678fd37182322ad9ca8 Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sun, 17 Jul 2022 16:54:20 -0600 Subject: [PATCH] Do not emit warnings on urls within `@link` tags Resolves #1980 --- CHANGELOG.md | 5 ++-- .../converter/plugins/LinkResolverPlugin.ts | 23 +++++++++++---- src/test/converter2/issues/gh1980.ts | 6 ++++ src/test/issueTests.ts | 29 +++++++++++++++++++ 4 files changed, 56 insertions(+), 7 deletions(-) create mode 100644 src/test/converter2/issues/gh1980.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e36b961d..a24cc780e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,14 +2,15 @@ ### Features +- Added defined in links for classes, enums, #180. - Added support for `*.ghe.com` and `*.github.us` GitHub enterprise domains for source links, #2001. - Expose `Converter.parseRawComment` for plugins to parse additional markdown files, #2004. -- Added defined in links for classes, enums #180. ### Bug Fixes -- Fixed missing `sources` property on signature reflections #1996. +- TypeDoc will no longer emit a warning for `{@link}` containing a URL, #1980. - `excludeNotDocumented` will no longer remove functions/methods/accessors which are documented, #1994. +- Fixed missing `sources` property on signature reflections #1996. ### Thanks! diff --git a/src/lib/converter/plugins/LinkResolverPlugin.ts b/src/lib/converter/plugins/LinkResolverPlugin.ts index a537bc8cf..d9dec5bd3 100644 --- a/src/lib/converter/plugins/LinkResolverPlugin.ts +++ b/src/lib/converter/plugins/LinkResolverPlugin.ts @@ -220,26 +220,37 @@ function resolveLinkTag( ) { let pos = 0; const end = part.text.length; + while (pos < end && ts.isWhiteSpaceLike(part.text.charCodeAt(pos))) { + pos++; + } + const origText = part.text; // Try to parse one const declRef = parseDeclarationReference(part.text, pos, end); - let target: Reflection | undefined; + let target: Reflection | string | undefined; if (declRef) { // Got one, great! Try to resolve the link target = resolveDeclarationReference(reflection, declRef[0]); pos = declRef[1]; } + 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; + } + } + // If resolution via a declaration reference failed, revert to the legacy "split and check" // method... this should go away in 0.24, once people have had a chance to migrate any failing links. if (!target) { const resolved = legacyResolveLinkTag(reflection, part); if (resolved) { warn( - `Failed to resolve {@link ${ - part.text - }} in ${reflection.getFriendlyFullName()} with declaration references. This link will break in v0.24.` + `Failed to resolve {@link ${origText}} in ${reflection.getFriendlyFullName()} with declaration references. This link will break in v0.24.` ); } return resolved; @@ -255,7 +266,9 @@ function resolveLinkTag( } part.target = target; - part.text = part.text.substring(pos).trim() || target.name; + part.text = + part.text.substring(pos).trim() || + (typeof target === "string" ? target : target.name); return part; } diff --git a/src/test/converter2/issues/gh1980.ts b/src/test/converter2/issues/gh1980.ts new file mode 100644 index 000000000..10e749133 --- /dev/null +++ b/src/test/converter2/issues/gh1980.ts @@ -0,0 +1,6 @@ +/** + * {@link http://example.com } + * {@link http://example.com | with text} + * {@link http://example.com jsdoc support} + */ +export const link = 123; diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts index 8c1d7799a..b7e488b97 100644 --- a/src/test/issueTests.ts +++ b/src/test/issueTests.ts @@ -599,6 +599,35 @@ export const issueTests: { equal(comments2, ["Comment for a", "Comment for b"]); }, + gh1980(project, logger) { + const link = query(project, "link"); + equal( + link.comment?.summary.filter((t) => t.kind === "inline-tag"), + [ + { + kind: "inline-tag", + tag: "@link", + target: "http://example.com", + text: "http://example.com", + }, + { + kind: "inline-tag", + tag: "@link", + target: "http://example.com", + text: "with text", + }, + { + kind: "inline-tag", + tag: "@link", + target: "http://example.com", + text: "jsdoc support", + }, + ] + ); + logger.discardDebugMessages(); + logger.expectNoOtherMessages(); + }, + gh1986(project, logger) { const a = query(project, "a"); equal(