Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
doberkofler opened this issue Jul 2, 2022 · 12 comments
Labels
bug Functionality does not match expectation wontfix Declining to implement

Comments

@doberkofler
Copy link

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
@doberkofler doberkofler added the bug Functionality does not match expectation label Jul 2, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jul 2, 2022

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
Copy link
Author

doberkofler commented Jul 3, 2022

@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
Copy link
Collaborator

Gerrit0 commented Jul 3, 2022

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
Copy link
Author

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:
image

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jul 3, 2022

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
Copy link
Author

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
Copy link
Collaborator

Gerrit0 commented Jul 6, 2022

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:

@Gerrit0 Gerrit0 added the wontfix Declining to implement label Jul 7, 2022
@Gerrit0 Gerrit0 closed this as not planned Won't fix, can't repro, duplicate, stale Jul 10, 2022
@frank-weindel
Copy link

frank-weindel commented Jul 14, 2022

@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
Copy link

Screen Shot 2022-07-14 at 10 54 15 AM

Screen Shot 2022-07-14 at 10 54 34 AM

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
Copy link
Author

@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
Copy link
Collaborator

Gerrit0 commented Jul 17, 2022

... 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.

@Gerrit0 Gerrit0 reopened this Jul 17, 2022
@doberkofler
Copy link
Author

Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Functionality does not match expectation wontfix Declining to implement
Projects
None yet
Development

No branches or pull requests

3 participants