Tracking issue for RFC 1946 - intra-rustdoc links

[nrc]

RFC: https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md
RFC PR: rust-lang/rfcs#1946

Todo:

• Land Implement RFC 1946 - intra-rustdoc links #47046
• Make it work with cross-crate imports (Support intra-doc links on cross-crate reexports #65983, Implement RFC 1946 - intra-rustdoc links #47046 (comment))
• Make it work for proc macros Intra-doc links doesn't work for proc macros #73173
• Make it warn more on resolution errors (Add warning if a resolution failed #49542)
• Make warnings/errors use better spans than the first line of docs
  • first step: attribute (Point to the rustdoc attribute where intralink resolution failed. #51111)
  • point to actual link in doc comment (Use spans pointing at the inside of a rustdoc attribute #51391)
  • Add lint for link resolution failure (Add lint for intra link resolution failure #51382)
• Implied Shortcut Reference Links (Implement implied shortcut links for intra-rustdoc-links #48335)
  • blocked on Tracking issue (Rustdoc): hoedown -> pulldown migration #44229 and Option to insert reference link definitions on demand pulldown-cmark/pulldown-cmark#121
• Enum variants and UFCS/associated methods (Fixes for intra-doc-links #47701)
• Primitives (Add primitive intra-links #49459)
• Use the right resolution scopes for inner doc comments on things that aren't modules (rustdoc intra links: Module-level doc uses parent module's namespace instead of own #55364)
• Handle fields and variants (Add support for variant and types fields for intra links #49512)
  • Handle fields inside struct variants (Intra doc enum variant field #66704)
• Support Self (intra-rustdoc links: Consider supporting Self #49583)
• Write documentation (Document intra-rustdoc links in the unstable book #66000)
• Stabilization (Stabilize intra-doc links #74430 - current impl is gated to only run on nightly, but does not require a feature gate)
• Handle methods from traits implementations
• Support anchors (Support anchors intra doc links #66675)
• Support missing primitive types (such as slices) (Intra-rustdoc links do not work for all primitives #63351)
• Allow referring to Self::item (for cmp on Ord)
• Fix current crate linking when no module is provided in the path (for example, Foo won't link to the crate's Foo type for some reason)
• doc(hidden) reexports can break intra-doc links (Cross-crate intra-doc links broken for functions when there's a doc(hidden) full-crate reexport involved #73363)
• Support associated items in contexts other than documenting a trait method (Fix intra-doc links for associated items #74489)

Other related issues:

• Suppress privacy errors with document-private-types (Rustdoc links to private types on private items generate a warning #74134, fix at rustdoc: Allow linking from private items to private types #74147)
• provide option to turn intra-link resolution errors into proper errors (rustdoc: provide option to turn intra-link resolution errors into proper errors #50082)

[QuietMisdreavus]

Preliminary implementation notes:

Getting just the links from the markdown is relatively straightforward. You'll need to do this twice, to capture the behavior in both the Hoedown and Pulldown markdown renderers. Thankfully, each has a way of capturing links as they are parsed from the document. (While capturing the link you can also look for the "struct/enum/mod/macro/static/etc" marker to aid in resolution down the line.)

In Hoedown, the render function in src/librustdoc/html/markdown.rs captures all the events as they are captured. Hoedown uses a system of registering callbacks on the renderer configuration to capture each event separately. The link event and its related linkfn function pointer signature are already present in the file, so you would need to create and use that callback to capture and modify links as they appear.

For Pulldown, the parser is surfaced as an Iterator of events. There are already a handful of iterator wrappers present in html/markdown.rs, so adding another one (and using it in the impl fmt::Display for Markdown farther down) shouldn't be a big deal. I'm... honestly not that familiar with how Pulldown represents link definitions in its Event/Tag enums, so more research would be needed to effectively get link text for that.

Now, with the links in hand, you need to do two things, neither of which i know offhand since they involve interfacing with the compiler:

• Attempt to parse the link as a path (if it's not a valid Rust path, just emit the URL as-is and skip the rest of this)
• Resolve the path in the "current" module (emit a warning if resolution fails)

Presumably there's a way to make the resolution come up with a DefId? Even after cleaning the AST, rustdoc still deals in those, so if that's the case there are ways to map that to the proper relative link.

[Manishearth]

I've got a WIP going on in https://github.com/manishearth/rust/tree/correct-resolver-fail , which works off of Misdreavus' WIP (they did most of the work).

[QuietMisdreavus]

Note that that branch is now live as #47046, which i'm polishing and finishing up.

[QuietMisdreavus]

Note for people watching this thread but not #47046: We're trying to wind that PR down to get a minimal version landed, so an initial implementation is fairly close.

[sgrif]

One thing that appears to not work in #47046 (and I don't think is ever explicitly addressed in the RFC) is how to link to primitives like u32 or bool.

[Manishearth]

Yeah I have to investigate that

[Manishearth]

@killercup @QuietMisdreavus should we turn the error into a warning ? I don't like the idea of crate docs breaking because someone introduced a name into a glob import

[killercup]

@Manishearth does rustdoc have some idea of "lint levels"? What are the current deprecation warnings? Just println!s?

[Manishearth]

We can just struct_span_warn instead. rustc can emit warnings not tied to actual warning names. There are no lint levels.

[killercup]

Alright, let's do that for now. In the end I'd really like to have a way to check the docs for errors but that's a more involved/fragile process I imagine. Manish Goregaokar <notifications@github.com> schrieb am Mi. 24. Jan. 2018 um 09:17:

…

We can just struct_span_warn instead. rustc can emit warnings not tied to actual warning names. There are no lint levels. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#43466 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABOXw-H_Wyi-zoTpfv_fqi-ovlRv5a9ks5tNucqgaJpZM4OiBhy> .

[Manishearth]

#47701

[Manishearth]

Shortcut links being implemented at #48335

[Manishearth]

Alright, so the current status of this is that we have a stack of PRs blocking all remaining major issues (#65983, #73363): #74347 -> #73566 -> #73101 -> #73365

Between @GuillaumeGomez, @jyn514, and myself, we hope to stabilize this shortly thereafter. @GuillaumeGomez will be filing an FCP but as we're currently mostly waiting for the final chips to fall in place, I wanted to front-load some of the discussions that may happen during that FCP. Hopefully when we make that FCP it is simply some rubber-stamping if we have these discussions earlier.

@rust-lang/rustdoc What are your thoughts on stabilizing this shortly after the last few patches land? I recall @ollie27 having some concerns. I don't recall if @kinnison has said anything on this point.

My position on this (I think this is shared by Guillaume and Joshua) is that this feature has been cooking on nightly for three years now. The cross-crate import issue was a blocker not because it was a major piece of functionality, but rather because there was a chance we wouldn't be able to implement it in a neat manner and would paint ourselves into a corner by committing to it. It's clear that that's not the case. If we're worried about the code for cross-crate imports itself being broken, that's what the release train schedule is for -- we can undo these patches and stabilization for twelve weeks if this happens.

[kinnison]

I think that once the remaining stack lands, we're in good shape to stabilise. There're bound to be corner cases we've not found etc. and documentation which could be improved, but getting this out and usable by the general developer community will be immensely useful.

[Manishearth]

#65983 has landed, so now we're ready for stabilization. #73363 should land soon

[Manishearth]

Stabilization PR is ready #74430

[jyn514]

It should be noted that in the RFC discussion it was determined that exact knowledge of the item type should not be necessary; only knowing the namespace should suffice. It is acceptable that the tool resolving the links allows (and successfully resolves) a link with the wrong prefix that is in the same namespace. E.g., given an struct Foo, it may be possible to link to it using [enum Foo], or, given a mod bar, it may be possible to link to that using [struct bar].

After #75079 this is no longer the case. Should the RFC be updated?

[Manishearth]

@jyn514 go for it

[runiq]

Triage: #74489 has been merged, so its mark can be checked, I believe?

[swfsql]

Hi, does someone knows how to write intra-rustdoc links to trait implementation on structs? I'm not sure if this is not implemented or if I'm writing incorrectly.

Have tried those, but they are not working:

[`<Struct as Trait>::f()`]
[`<Struct as Trait>::f`]
(link)[<Struct as Trait>::f]
(link)[<Struct as Trait>::f()]

[jyn514]

@swfsql #74563