warning Failed to resolve ... with declaration references. This link will break in v0.24.

[doberkofler]

Search terms

warning Failed to resolve

Expected Behavior

No warning

Actual Behavior

warning Failed to resolve {@link https://stackoverflow.com/questions/92720/jquery-javascript-to-replace-broken-images} in data/employee.getFallbackImage with declaration references. This link will break in v0.24.

Steps to reproduce the bug

/**
*	Return a fallback image if user image not found
*
*	Usage {@link https://stackoverflow.com/questions/92720/jquery-javascript-to-replace-broken-images}
*	Usage {@link https://stackoverflow.com/questions/8124866/how-does-one-use-the-onerror-attribute-of-an-img-element}
*	@returns {string} - The path to the fallback image
* 	@example img.onerror=getFallbackimage()
*/
export function getFallbackImage(): string {
	return 'xxx';
}

Environment

• Typedoc version: 0.23.5
• TypeScript version: 4.7.4
• Node.js version: 18.4.0
• OS: maCOS 12.2

[Gerrit0]

Web links are not a valid declaration reference, this is a valid warning. You should use a markdown link instead.

This might be something that I could be convinced to add support for given that JSDoc for some reason decided to allow it, but I'm not aware of any reasons to use it over a regular markdown link.

[doberkofler]

@Gerrit0 Could you elaborate on what a markdown link is or how this @link would need to be rewritten. Just using regular html markdown like <a href="https://stackoverflow.com/questions/92720/jquery-javascript-to-replace-broken-images">Usage</a> does not seem to end up correctly in the documentation.

[Gerrit0]

Markdown links: https://www.markdownguide.org/basic-syntax/#links

Your html should work too with the default settings, maybe you're rendering to markdown and giving it to some other pipeline which doesn't support in-line html?

[doberkofler]

I have with the markdown syntax as well, but it does not seem to work as expected.

typedoc.json:

{
	"entryPoints": [
		"./src"
	],
	"entryPointStrategy": "expand",
	"out": "doc",
	"exclude": [
		"node_modules"
	]
}

source:

/**
 * Return the total of two numbers.
 * 
 * 	<a href="https://duckduckgo.com">Duck Duck Go</a>
 * 	[Duck Duck Go](https://duckduckgo.com)
 * 
 * @params p1 - The first number
 * @params p2 - The second number
 * @returns The total
 */
export function add(p1: number, p2: number): number {
	return p1 + p2;
}

result:

[Gerrit0]

You indented it by 4 spaces. That's (one of several) markdown syntaxes for a code block. TypeDoc does very little processing, and passes your comment on to Marked, which is responsible for this behavior.

[doberkofler]

It was actually a tab but thank you very much for finding the problem.
Given the tricky markdown syntax, I think it would be nice to support the @link syntax with an external URL.

[Gerrit0]

At this point, I'm leaning towards not allowing this. Using a tag implies that the link is intended to be resolved by TypeDoc. There's no point in giving this link to TypeDoc unless you're expecting it to do something with the link... and it doesn't.

There are several markdown alternatives to this:

http://example.com (if you have marked's gfm option on to make it behave more like GitHub's markdown)
<http://example.com>
<a href="http://example.com">link text</a>
[link text](http://example.com)

Notes:

• You can override marked's configuration with the markedOptions option
• Marked's options are listed at https://marked.js.org/using_advanced#options

[frank-weindel]

@Gerrit0 According to TSDoc docs, URLs are allowed in {@link}:
https://tsdoc.org/pages/tags/link/

/**
 * Let's learn about the `{@link}` tag.
 *
 * @remarks
 *
 * Links can point to a URL: {@link https://github.com/microsoft/tsdoc}
 *
 * Links can point to an API item: {@link Button}
 * ...
 */

I'm fine with using markdown links, however they don't work very nicely in a @see tag, at least in VS Code.

An example of using {@link <URL>} in a @see tag is also shown in TSDoc documentation:

https://tsdoc.org/pages/tags/see/

/**
 * Parses a string containing a Uniform Resource Locator (URL).
 * @see {@link ParsedUrl} for the returned data structure
 * @see {@link https://tools.ietf.org/html/rfc1738|RFC 1738}
 * for syntax
 * @see your developer SDK for code samples
 * @param url - the string to be parsed
 * @returns the parsed result
 */
function parseURL(url: string): ParsedUrl;

[frank-weindel]

What a markdown link looks like in VSCode. Functionally its fine, though the syntax highlighter isn't fond of it. (I realize that isn't in the scope of TypeDoc, but wanted to document it here for reference)

[doberkofler]

@frank-weindel Thank you for the update. I still believe that support for @link syntax with an external URL would be a helpful feature.

[Gerrit0]

... no idea how I missed that when adding support for declaration references. I guess I started with https://tsdoc.org/pages/spec/overview/ and never actually looked at @link.