Tracking issue for RFC 1946 - intra-rustdoc links

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)

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.

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).

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

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.

Auto merge of #47046 - Manishearth:intra-doc-links, r=eddyb,Guillaume…

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.

Yeah I have to investigate that

@killercup

@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

@Manishearth

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

@ollie27

@ollie27 We have had a functional implementation for three years now. It has been used in the stdlib docs for ages, and is used across the ecosystem. The ability for reexports to work correctly was a blocker to stabilization, but it is not a huge feature that will be used a lot. The reason stabilization was blocked on reexports was that we determined that the bug fix could be complicated and might require rearchitecting the feature, which made us reluctant to stabilize earlier.

seeing if it can fix the issues it was designed for (#32129, #32130)

I hadn't seen these issues earlier, and we should absolutely fix them using intra doc links, but I don't want to block stabilization on that. We've had this feature mostly working for ages.

@GuillaumeGomez

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.

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.

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

Stabilization PR is ready #74430

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?

@jyn514

@jyn514 go for it

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

Rollup merge of rust-lang#74430 - Manishearth:stabilize-intra-doc, r=…

Auto merge of rust-lang#74430 - Manishearth:stabilize-intra-doc, r=Ma…

Use intra rustdoc links

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()]

@swfsql

@swfsql #74563

Navigation Menu

Repository navigation

Tracking issue for RFC 1946 - intra-rustdoc links #43466

155 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking issue for RFC 1946 - intra-rustdoc links #43466

Description

Activity

QuietMisdreavus commented on Sep 19, 2017

Manishearth commented on Dec 28, 2017

QuietMisdreavus commented on Dec 28, 2017

QuietMisdreavus commented on Jan 8, 2018

sgrif commented on Jan 23, 2018

Manishearth commented on Jan 24, 2018

Manishearth commented on Jan 24, 2018

killercup commented on Jan 24, 2018

155 remaining items

Manishearth commented on Jul 9, 2020

Manishearth commented on Jul 9, 2020

Manishearth commented on Jul 15, 2020

kinnison commented on Jul 16, 2020

Manishearth commented on Jul 17, 2020

Manishearth commented on Jul 17, 2020

jyn514 commented on Aug 19, 2020

Manishearth commented on Aug 20, 2020

runiq commented on Sep 4, 2020

swfsql commented on Oct 18, 2021

jyn514 commented on Oct 18, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions