More control delegated for external link resolvers

[captain-torch]

Adding external link resolvers was a great idea, but in fact, it is useless for {@link} tags which cannot be resolved (from documentation), because linkResolver passes into external resolvers only DeclarationReference, that will be invalid for links in formats that is not supported. So external resolver will know about fact that some link can't be resolved, but can't do anything
about it.

I offer an improvement:

• Pass additional information (part: CommentDisplayPart and reflection: Reflection) to external resolver
• Allow external resolver control both target and text of link
• Add an exported ExternalResolveAttempt and ExternalResolveResult types as API for external resolver

[Gerrit0]

I like the idea of giving more control here... a few comments, and a question:

Why should code have access to the reflection containing the link when resolving a link to something outside of the documentation?

[Gerrit0]

Shouldn't these be non-optional, given your changes the array type above?

[captain-torch]

It was made optional because of usage of this function in LinkResolverPlugin (line 53). I didn't catch the purpose of using this function there, and for safety decided to change resolveExternalLink signature in order to avoid modifying of this code.

[Gerrit0]

That is for links to types declared outside of the project, e.g.:

import { Bar } from "external-lib"
export function foo(bar: Bar) {}

[Gerrit0]

and reflection: Reflection

There might be a legitimate use case for this, but I'm not seeing it. Why should code intended to resolve links to pages outside the documentation have this?

[captain-torch]

In my case, we have few libraries, which have imports between them, but typedoc combines them all into one useful documentation (by another plugin). With current logic, typedoc resolves links to our own entities like it is external. But in fact, somewhere in reflections tree is a reflection that contains information about this entity, and I passes reflection, where link is located, to build relative links between these entities.

[Gerrit0]

That shouldn't be necessary in an ideal world... but given how much time I'm spending here... probably not going to be fixed soon, and this isn't a huge wart. I guess I'm fine with it.

[Gerrit0]

Thanks! I'll get this released by Monday at the latest.