winit icon indicating copy to clipboard operation
winit copied to clipboard

Prefer `[foo][bar]` over `[foo](bar)` for intra-doc links

Open daxpedda opened this issue 2 years ago • 2 comments

Follow-up to a discussion here: https://github.com/rust-windowing/winit/pull/3178#discussion_r1371280634.

The logic here is that [foo](bar) can be used for inline links or intra-doc links, but [foo][bar] can be used for labels or intra-doc links, so if no label is present, it can only be a intra-doc link, making this less ambiguous and more robust to error check.

daxpedda avatar Oct 25 '23 15:10 daxpedda

For reference: still waiting for some feedback in https://github.com/rust-lang/rust/pull/117178.

daxpedda avatar Nov 09 '23 22:11 daxpedda

Apparently the conclusion was that there is no preference: https://github.com/rust-lang/rust/pull/121021.

I also double checked and AFAICT Rustdoc will properly generate an error regardless. So the only difference is that []() will generate a dead link but [][] will not, but its not really an issue because CI should always catch it.

Personally I would still prefer [foo][bar] over [foo](bar) despite there not being any official recommendation by Rustdoc but us being consistent in Winit. So if we have consensus I would still like to move forward with this.

daxpedda avatar Feb 14 '24 08:02 daxpedda