Support custom link format

[Aurel300]

A couple of issues with dox stem from incorrect type and field resolution. (#252, #203, possibly also #241 and #184?). The current resolver for links (https://github.com/HaxeFoundation/dox/blob/master/src/dox/MarkdownHandler.hx#L45) could be smarter – check what module a type is in, check the imports, prefer to link to platform-agnostic types, etc etc.

I suggest we instead use a custom link format to link to types and fields properly. Any new docs would / should be written with:

• <pack:some.package> - to link to a package
• <type:some.package.SomeType> - to link to a type
• <type:some.package.SomeType.SubType> - to link to a subtype
• <field:some.package.SomeType.someSpecificField> to link to a field (variable, property, method)
• possibly other special syntax

This is not a complicated change for the resolver. We can keep the old docs as they are or perhaps systematically find all links and make sure they are correct (a bit time consuming but once done it is done).

[Gama11]

Hm, I'm not convinced that's a good idea. A few thoughts:

• I doubt many people (myself included) would bother to adjust their API docs to use that link format, since it mostly works fine already apart from a few edge cases.
• It hurts the readability of docs when reading them non-formatted / in the sources.
• The syntax seems too random / obscure. Dox doc comments use markdown, so links should probably be inspired by markdown link syntax as well, i.e. [](). VSCode API docs seem to use this format (might be a JsDoc or TS thing?), which is at least markdown, but it still seems better to not need that at all.

It seems like this should be solvable simply by Haxe providing more info and/or link resolving being smarter.

[Aurel300]

• This is not necessarily a breaking change, since the old resolution would still work. Or we could enable it with a flag.
• Readability is hurt a little bit I guess. Though I usually read the docs in the rendered view anyway.
• The <...> brackets are not random, they are Markdown links without a text. To describe what you are linking to, you would use [here is a field](field:somepackage.Type.field).

[Gama11]

Huh, really, I've never seen that style of markdown link.. probably because it's rather pointless most of the time, because URLs are usually made clickable anyway without <>.

I realize it's not a breaking change, but that wasn't really my point. I just think people probably can't be bothered to write links like that, since links already work fine as is with most things (I certainly wouldn't change doc comments in libs I maintain).

Especially the part about needing to tell dox whether it's a package, type or field just feels like a weird workaround / a case of "the tools I'm using are dumb" - Dox is interfacing with the compiler after all, who knows this stuff (indirectly via XML, but still), so it seems like there should be a better solution to this.

[Gama11]

Btw, I can certainly see the use case for "aliasing links" such as [here is a field](somepackage.Type.field), but without the field: / type: / pack: part.

[Aurel300]

I agree there should be a better solution. But it also seems there isn't one at the moment, or rather such a solution might involve a lot of work.

The syntax was just an example. If it is possible for dox to understand unambiguously what a particular dot-separated path refers to, that's fine. I might be mistaken in thinking there are a couple of cases where the path might refer to multiple things?

[Gama11]

I mean, in principle, fully qualified paths shouldn't be ambigious. Otherwise the compiler would have trouble too.

[Aurel300]

I might just be confused because of this https://github.com/HaxeFoundation/haxe/issues/6525

[mehdadoo]

But, the first question is, what is the current syntax for linking to another Class?

Link Name

? thanks