-
Notifications
You must be signed in to change notification settings - Fork 36
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
Support custom link format #253
Comments
Hm, I'm not convinced that's a good idea. A few thoughts:
It seems like this should be solvable simply by Haxe providing more info and/or link resolving being smarter. |
|
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. |
Btw, I can certainly see the use case for "aliasing links" such as |
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? |
I mean, in principle, fully qualified paths shouldn't be ambigious. Otherwise the compiler would have trouble too. |
I might just be confused because of this HaxeFoundation/haxe#6525 |
But, the first question is, what is the current syntax for linking to another Class? ? |
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)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).
The text was updated successfully, but these errors were encountered: