add lint names to `rustup doc` topic list

[lolbinarycat]

Problem you are trying to solve

it is inconvenient to try to navigate to the page for a specific lint in the local documentation.

Solution you'd like

typing rustup doc lintname takes you to the page for that lint. this would work for rustc lints, rustdoc lints, clippy lints, and potentially other tool lints.

for example, rustup doc rustdoc::broken_intra_doc_links would take you to file:$TOOLCHAIN/share/doc/rust/html/rustdoc/lints.html#broken_intra_doc_links.

Notes

No response

[rami3l]

@lolbinarycat Thanks for filing this issue!

Indeed, rustup doc has kind of fallen into disrepair over the years, so the user experience might not be optimal.

Your proposal is perfectly valid, it's just that I might not implement it as described above now that we have rustup doc --rustdoc for that already.

The relevant snippet is here:

rustup/src/cli/rustup_mode.rs

Lines 1499 to 1505 in 708ffd6

	let doc_url = if let Some(topic) = topic {
	topical_path = topical_doc::local_path(&toolchain.doc_path("").unwrap(), topic)?;
	topical_path.to_str().unwrap()
	} else {
	topic = doc_page.name();
	doc_page.path().unwrap_or("index.html")
	};

... which is not idiomatic, of course, since whenever topic (e.g. std::mem) is present, we won't even look at doc_path (e.g. --rustdoc).

So I think we should consider these two altogether, for instance allowing rustup doc --rustdoc lints, and that's pretty easy.

However, there is already enough magic in the current implementation in the way it searches for stdlib items, so we should never explicitly point to lints just like we did with stdlib... I wonder how this will eventually end up like.
Does rustup doc --rustdoc lints::broken_intra_doc_links look okay to you?

I mean, we can try with the following semantics with lints::broken_intra_doc_links:

1. Look for lints/broken_intra_doc_links/index.html.
2. Look for lints/broken_intra_doc_links.html.
3. Look for lints.html. If it exists, resolve to lints.html#broken_intra_doc_links.
4. Throw an error.

PS: I have manually verified that this algorithm, if implemented correctly, will work with rustc, rustdoc and clippy books.

[lolbinarycat]

However, there is already enough magic in the current implementation in the way it searches for stdlib items, so we should never explicitly point to lints just like we did with stdlib...

Aren't search engines generally supposed to be "magic"?

Although, ideally, it would be possible to unify this logic with something that does the same for documentation generated by cargo doc...

[rami3l]

However, there is already enough magic in the current implementation in the way it searches for stdlib items, so we should never explicitly point to lints just like we did with stdlib...

Aren't search engines generally supposed to be "magic"?

@lolbinarycat I have to admit that I don't use offline docs that often, so I might not be the best person to answer your questions, but I personally haven't expected this to work like a search engine... I might say it should work pretty much like "I'm Feeling Lucky" though.

BTW, by "search engine", are you referring to something along the lines of https://zealdocs.org?

Although, ideally, it would be possible to unify this logic with something that does the same for documentation generated by cargo doc...

I have reservations about this. It seems to me that, although I'd pretty much like to have something like that during my flights, rustup doc is not the right abstraction for this task, since rustup is still mostly around managing all the stuff that comes with the toolchain distribution 🤔

[lolbinarycat]

I have reservations about this. It seems to me that, although I'd pretty much like to have something like that during my flights, rustup doc is not the right abstraction for this task, since rustup is still mostly around managing all the stuff that comes with the toolchain distribution 🤔

Well, yeah, the idea would be to factor out the core logic behind rustup doc into its own tool, then rustup doc itself would become a trivial wrapper around this tool (with a decent transitional period to account for old toolchains that don't include this tool), and cargo could provide its own wrapper around it.

[rami3l]

I have reservations about this. It seems to me that, although I'd pretty much like to have something like that during my flights, rustup doc is not the right abstraction for this task, since rustup is still mostly around managing all the stuff that comes with the toolchain distribution 🤔

Well, yeah, the idea would be to factor out the core logic behind rustup doc into its own tool, then rustup doc itself would become a trivial wrapper around this tool (with a decent transitional period to account for old toolchains that don't include this tool), and cargo could provide its own wrapper around it.

@lolbinarycat I see what you mean.

In the short term I still see #4070 as a valid first move forward since it's an unnecessary restriction to the current feature set...

[rami3l]

I'm closing the this issue in favor of #4165, as the way forward is a bit clearer over there (TLDR: modifying the ending of the URL to form something like https://doc.rust-lang.org/rustdoc/index.html?search=broken_intra_docs). Thanks again for the feedback, and maybe we can continue our discussion over there?