Update intra-doc link documentation to match the implementation

[jyn514]

r? @Manishearth
cc @camelid @m-ou-se

Relevant PRs:

• Fix intra-doc links for associated items #74489
• Fix intra-doc links for non-path primitives #80181
• Remove disambiguators from intra doc link text #76078
• Resolve intra-doc links on additional documentation for re-exports in lexical scope #77519
• Resolve items for cross-crate imports relative to the original module #73101

Relevant issues:

• Intra-doc links do not resolve associated items for blanket impls #78800
• Consider warning when intra-doc links fail on a cross-crate re-export #77200
• intra-doc links: Links with unexpected characters are silently ignored #77199 / rustdoc does not warn about broken links if they contain . or [] #54191

I haven't documented things that I consider 'just bugs', like #77732, but I have documented features that aren't implemented, like #78800.

[m-ou-se]

Nice!

Maybe it's good to also mention that both [...](Bar) and [..][Bar] works.

[jyn514]

Good idea, done.

[camelid]

Maybe it's good to also mention that both [...](Bar) and [..][Bar] works.

That's weird, I've found that [...](Bar) doesn't always work for me. Is it supposed to work?

[camelid]

We should probably note somewhere that non-intra-doc links are case-insensitive; see #80882.

[jyn514]

Ugh, #80882 is a mess. I think I'd prefer to see what the plan is there before updating the documentation.

[camelid]

It may not be necessary, but do you want to note that the type namespace includes modules?

[jyn514]

I would prefer not to; if you get it wrong it will be clear from the error message. If we mention modules we should also say functions are in the value namespace, though.

[camelid]

I'm not sure if it's a good idea to link to the source code here. For one, it will very easily become out-of-date because it's tied to a particular commit. I think we should either skip this or include the list directly in the documentation.

[jyn514]

Hmm, I kind of prefer not to tie this down so we can update it in the future. Maybe I could change the commit hash to master instead? That might have wrong line numbers though.

[camelid]

Maybe I could change the commit hash to master instead? That might have wrong line numbers though.

Yeah, I think that would be very confusing.

Hmm, I kind of prefer not to tie this down so we can update it in the future.

What do you mean? Documenting it isn't "tying it down".

[Manishearth]

So, this is a not a reference, this is a book, and I don't think it should go into that much detail. We do not need to document every last corner of the implementation here. Let's just drop this section.

[jyn514]

That's weird, I've found that ... doesn't always work for me. Is it supposed to work?

It should, if not that's a bug. Feel free to open an issue if you run into it again.

[camelid]

These two paragraph seem contradictory. The first one says that links are resolved in the module where the item is defined, even when it's re-exported, while the second says that documentation you add on a re-export will be resolved in the re-export crate. Which one is it? :P

[jyn514]

The original links will be resolved in the original scope. The new links will be resolved in the new scope. The idea is for this to work:

// crate 1
/// Link to [f()]
pub struct S;
pub fn f() {}

// crate2
/// Link to [g()]
pub use crate1::S;
pub fn g() {}

[camelid]

I think you should say something like that in the docs, because I couldn't tell what you meant from the way it is right now.

[jyn514]

I couldn't think of a way to explain this better, but I did add an example of both scenarios.

[Manishearth]

I'd collapse this into a single sentence. Most people don't need to care about this, and rustdoc helps with diagnostics when they do.

[Manishearth]

I'd collapse this into a single sentence. Most people don't need to care about this.

[Manishearth]

overall this is written a little like a full reference; we don't need to cover everything, we should largely give space to things that are important to most users.

[Havvy]

@Manishearth So....where does reference material for rustdoc go?

[Manishearth]

I don't think there needs to be such in depth reference material for rustdoc. Like, so far in this pull request there's only one thing that I feel doesn't belong, and it's in the "rustdoc will ignore things that look like URLs" bit, which tbh i feel doesn't need to be documented at all, but either way, it's an extremely minor thing, and there aren't enough of these to warrant a separate book.

The rest is just a matter of style: A reference book can get away with being as precise as it can, but this book should be concise when talking about things that don't matter as much, like the disambiguators -- nobody needs to learn about them, in fact I'd argue they don't really belong in this book either, but it's fine to just have a sentence.

[jyn514]

I don't think there needs to be such in depth reference material for rustdoc. Like, so far in this pull request there's only one thing that I feel doesn't belong, and it's in the "rustdoc will ignore things that look like URLs" bit, which tbh i feel doesn't need to be documented at all, but either way, it's an extremely minor thing, and there aren't enough of these to warrant a separate book.

I feel like there should be a reference somewhere. It doesn't need to be the rustdoc book, but right now it's hard to find how things work and why. Really this is an ongoing problem I've seen with rustdoc where things are underspecified and changes happen without much discussion. Here are some concrete examples:

• const _ is ignored, but nothing else named _:

  rust/src/librustdoc/visit_ast.rs

  Line 341 in 26e5bcd

  // Underscore constants do not correspond to a nameable item and

• What are the rules for inlining? At all? I'm the team lead for rustdoc and I don't know: Rustdoc: #[doc(hidden)] should not apply recursively #81980 (comment). I don't even know if that's meant to be a bug or a feature; I feel that about lots of parts of rustdoc.
• Why are some const functions not shown in docs (rustc_const_unstable)? Feature request: show rustc_const_unstable in generated documentation #81371
• Why aren't links from trait pages to themselves autogenerated? Why only for traits? Restore linking to itself in implementors section of trait page #81313

All of these individually are small, but they build up. I feel like "whatever the implementation does" is really not a good way to build software, especially when there's no much discussion about these changes and they just happen.

[Manishearth]

I think for a first pass this stuff should be long comments in the source, or just extra documentation in a docs folder. We could have a reference that strongly specifies rustdoc, but there's a lot we'd have to specify, and I don't think we have the bandwidth to do that. You're right that "whatever the implementation does" isn't great for software, but that doesn't mean that everything needs to be in design docs outside of the implementation. Using long comments or doc/foo.md folders is fine.

[Manishearth]

But I am strongly against putting something that basically only implementors need to care about in the book. My opposition to a separate in-depth reference is mostly that it's a lot of work for very little benefit, and we can get something much smaller done better, but I'm not strongly against that.

Having a doc/ folder for random markdown files seems like a decent first step for pinning down things for implementors.

[jyn514]

But I am strongly against putting something that basically only implementors need to care about in the book.

I agree it probably doesn't fit in the book, but I don't think this is something only implementors need to worry about. These are all user-facing things that affect behavior, even if they're edge cases.

Anyway, I'll update this to not have quite so much detail and maybe open a tracking issue for the other things.

[Manishearth]

I'll point out that subtle edge cases of a lot of the things in the compiler are not user-facing-documented either. Things like "we try to figure out if something is supposed to be an intra-doc link with magic" and "type inference does magic" should be documented, but the precise details of what the magic is doesn't really need to be user-facing. It's sufficient for people to know that magic is going on, and if there are problems they can root cause it to the magic, and do something to appease the magic. Understanding the magic can be useful here, but really what you just need to know is how to bypass it; and for intra-doc links that's basically using the discriminants, and for inference it's using specific types.

[jyn514]

This is ready for review (I finally figured out the CI error).

[Manishearth]

@bors r+ rollup

[Manishearth]

@bors r+ rollup

[bors]

📌 Commit c2694f1 has been approved by Manishearth