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.