# Pre-RFC: standard form to reference things **URL:** \ **Category:** Uncategorized\ **Created:** [October 3, 2015, 10:37pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720 "2015-10-03T22:37:38Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [October 3, 2015, 10:37pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/1 "2015-10-03T22:37:38Z")
In javadoc, it’s easy and useful to link to types, functions and/or fields. I think that Rust would do well to follow that example and define a canonical link format that could be used in rustdoc and annotations (I’d like to use it in my proposed deprecation feature). The format should: - use the current namespace so things in scope can be used directly; this reduces duplication and allows to reference `extern crate`s (however, those crates would then become a doc dependency) - be readable as-is, so it should be as near as possible to our `x::y` syntax - be unambiguous - be easy to learn and reasonably hard to get wrong What do you folks think? ---
**Author:** ![jschievink](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jschievink/32/3063_2.png) [@jschievink](https://internals.rust-lang.org/u/jschievink)\ **Post date:** [October 3, 2015, 11:42pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/2 "2015-10-03T23:42:18Z")
👍 from me, even though this seems a bit late, so it might take a (long) while to transition. Possible syntax: `{path::to::Thing#method_or_field}`. I don't think this has any meaning in markdown, so we should be able to use it for our own purposes. Rustdoc should convert all of these into links to the respective page and strip the `{}`. This can possibly even be done inside of code blocks, since it either isn't very useful Rust or even illegal Rust (and it would be whitespace-sensitive to enforce a common style for readability and to further differentiate from Rust code). Some more thoughts: - If a path isn't resolved, should it be a hard error (generate no docs) or generate broken docs? Or should rustdoc generate broken docs, print an error and return an error code? - Paths into `std` and other included-by-default crates must be handled differently (the link has to point to the official documentation, since local docs don't exist) - We have to watch out for references to private fields/items, obviously, but these might be useful when generating internal documentation for an executable - in fact, their availability depends on which rustdoc passes are run on the crate that contains them > [@llogiq](#): > > this reduces duplication and allows to reference extern crates (however, those crates would then become a doc dependency) I'm not sure what you mean by this. Are there special-cased doc dependencies? Rustdoc will already build docs for all dependencies, so they are available. ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [October 4, 2015, 12:32am UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/3 "2015-10-04T00:32:36Z")
No, I meant dev-dependency, but I could imagine making a special rustdoc-only `extern crate` syntax, which would reduce the dependency to doc builds. ---
**Author:** ![killercup](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/killercup/32/3256_2.png) [@killercup](https://internals.rust-lang.org/u/killercup)\ **Post date:** [October 4, 2015, 11:25am UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/4 "2015-10-04T11:25:26Z")
> [@llogiq](#): > > In javadoc, it's easy and useful to link to types, functions and/or fields. FTR, the [javadoc](http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDDIECH) syntax is: ```md Use the {@link #getComponentAt(int, int) getComponentAt} method. ``` [jsdoc](http://usejsdoc.org/tags-inline-link.html) is the same, but also allows this to be used in markdown links (`[text]{@link namepathOrURL}`). This syntax could also work for Rust, though I'd like to not use `#` for methods as we can already access those with `::` (and fields with `.`). ---
**Author:** ![bluss](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/bluss/32/2264_2.png) [@bluss](https://internals.rust-lang.org/u/bluss)\ **Post date:** [October 4, 2015, 3:02pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/5 "2015-10-04T15:02:58Z")
Does markdown have any facility for extension syntax, or some recommendation for this? Would it be possible to just use URLs, with the `rustdoc:` scheme? For example: `[link title](rustdoc: std::io::Read)`, ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [October 4, 2015, 3:49pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/6 "2015-10-04T15:49:12Z")
Why not rust:Read (as long as `std::io::Read` is in scope)? ---
**Author:** ![killercup](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/killercup/32/3256_2.png) [@killercup](https://internals.rust-lang.org/u/killercup)\ **Post date:** [October 4, 2015, 3:56pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/7 "2015-10-04T15:56:55Z")
Using a new URL schema like `rustdoc://std::path::Path` might be a good idea. (Where the part after the `rustdoc://` can be anything that could also be resolved by a `use`.) We might want differentiate between named links like `[the Path docs](rustdoc://std::path::Path)` and “plain” references, though (e.g. ``, rendered as “[Path](http://doc.rust-lang.org/std/path/struct.Path.html)”). (The nice thing is that these do not require us to invent new Markdown-compatible syntax.) ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [October 4, 2015, 4:04pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/8 "2015-10-04T16:04:17Z")
Yeah, that’s mostly what I thought, though I’m not keen on `rustdoc://`, that seems a bit long. As I said before, `rust:` as a prefix should be sufficient, the double slashes aren’t actually required for a link, AFAIK. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [October 4, 2015, 5:18pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/9 "2015-10-04T17:18:11Z")
> [@bluss](#): > > Does markdown have any facility for extension syntax, or some recommendation for this? Markdown itself does not. I haven't checked CommonMark lately, but I think it was stated to be one of the goals of the project. I think that having something like this would be nice, but I really want Rust to play nicely with the rest of the universe. So if we do have to blaze a trail here, I want to make sure that it fits with whatever happens upstream in markdown proper. ---
**Author:** ![killercup](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/killercup/32/3256_2.png) [@killercup](https://internals.rust-lang.org/u/killercup)\ **Post date:** [October 4, 2015, 7:28pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/10 "2015-10-04T19:28:23Z")
Feel free to bikeshed the URL schema, `rust:std::path::Path` might work as well but to me looks weird because of the single colon at the start when all other components use two. ---
**Author:** ![nikomatsakis](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nikomatsakis/32/5410_2.png) [@nikomatsakis](https://internals.rust-lang.org/u/nikomatsakis)\ **Post date:** [October 5, 2015, 7:07pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/11 "2015-10-05T19:07:47Z")
So I think we should have some clear and unambiguous form to link, but I’d also like it if rustdoc could make a best effort guess at linking things as well. i.e., if I write `foo`, and there is a fn or module called `foo` in scope, I want it to just link. Maybe if there is ambiguity it could link to a search, as well. ---
**Author:** ![Gankra](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/gankra/32/6002_2.png) [@Gankra](https://internals.rust-lang.org/u/Gankra)\ **Post date:** [October 5, 2015, 7:23pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/12 "2015-10-05T19:23:45Z")
Neither Markdown nor CommonMark specify any form for extension (I briefly followed this idea in the CommonMark forums but it was a worthless conversation). However a custom uri isn’t really an extension IMO. AFAIK we’ve just been blocked on “ugh hoedown is C bleugh”. This is why I was excited about pulldown-cmark getting relicensed. Someone just needs to swap hoedown out with it, and then we can easily extend the whole thing by mapping over its token stream. ---
**Author:** ![Gankra](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/gankra/32/6002_2.png) [@Gankra](https://internals.rust-lang.org/u/Gankra)\ **Post date:** [October 5, 2015, 7:25pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/13 "2015-10-05T19:25:04Z")
Note that this is non-trivial since cmark has two deps. It may involve solving the “bootstrap with cargo” problem. ---
**Author:** ![hauleth](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hauleth/32/1322_2.png) [@hauleth](https://internals.rust-lang.org/u/hauleth)\ **Post date:** [March 30, 2016, 8:46am UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/14 "2016-03-30T08:46:02Z")
That is the reason why I would like to opt in for using ASCIIDoc wirh Markdown compatibility layer ([yes, this is an official thing](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#markdown-compatibility)). ---
**Author:** ![matklad](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/matklad/32/12266_2.png) [@matklad](https://internals.rust-lang.org/u/matklad)\ **Post date:** [March 30, 2016, 12:24pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/15 "2016-03-30T12:24:32Z")
Here is how this is done in Kotlin: [https://kotlinlang.org/docs/reference/kotlin-doc.html#linking-to-elements](https://kotlinlang.org/docs/reference/kotlin-doc.html#linking-to-elements) The interesting pieces are minimal syntax `[some_thing]` and > Names in links are resolved using the same rules as if the name was used inside the element being documented. In particular, this means that if you have imported a name into the current file, you don’t need to fully qualify it when you use it in a KDoc comment. ---
**Author:** ![matklad](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/matklad/32/12266_2.png) [@matklad](https://internals.rust-lang.org/u/matklad)\ **Post date:** [March 30, 2016, 1:06pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/16 "2016-03-30T13:06:34Z")
Hm, and what about this horrible hack? You type ```rust `foo` ``` to get a code snippet and ```rust ` foo` ``` with a leading space to get a link (provided that `foo` is in scope). This is backwards compatible with stock markdown, uses `code` syntax for code, and allows detection of broken links in docs. ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [March 30, 2016, 6:35pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/17 "2016-03-30T18:35:38Z")
I don’t like it, it’s too easy to link by accident. ---
**Author:** ![matklad](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/matklad/32/12266_2.png) [@matklad](https://internals.rust-lang.org/u/matklad)\ **Post date:** [March 30, 2016, 7:48pm UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/18 "2016-03-30T19:48:31Z")
I would say that it’s too easy **not** to link by accident with this syntax, which is worse. If accidental link works, then it may be a good thing. If it does not work, then it is detected by `rustdoc`. ---
**Author:** ![lifthrasiir](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/lifthrasiir/32/24_2.png) [@lifthrasiir](https://internals.rust-lang.org/u/lifthrasiir)\ **Post date:** [April 4, 2016, 7:31am UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/19 "2016-04-04T07:31:39Z")
I have actually supported the link label syntax (`[foo::bar]`) for a long time. It is natural in Markdown/CommonMark, as one may suppose that there is an implicit label target for such labels, and the link label can contain any kind of letters required for full qualification ([spec](http://spec.commonmark.org/0.25/#link-label)). The main issue on supporting this syntax was that I’m not sure if [Hoedown](https://github.com/rust-lang/hoedown/) is capable for customizing link targets before the resolution. ---
**Author:** ![llogiq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/llogiq/32/13692_2.png) [@llogiq](https://internals.rust-lang.org/u/llogiq)\ **Post date:** [March 25, 2019, 8:25am UTC](https://internals.rust-lang.org/t/pre-rfc-standard-form-to-reference-things/2720/20 "2019-03-25T08:25:15Z")
Closed on March 25, 2019, 8:25am UTC This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.