rustdoc: implement unprefixed html class / id lint

[notriddle]

https://internals.rust-lang.org/t/proposed-lint-rustdoc-unprefixed-html-id/18099

[rustbot]

r? @jsha

(rustbot has picked a reviewer for you, use r? to override)

[notriddle]

Some questions we'll want to address before merging this (besides the obvious question of whether this is worth doing at all, which can be answered in an FCP):

• Right now, it separates the crate prefix from the rest of the identifier with _. This might not be the best choice.
• This lint is being landed insta-stable. Is that okay?
• Is crate name the right choice for the prefix?

[CAD97]

I'm essentially just a random user, so feel free to take this with a grain of salt, but

I have a small preference that rustdoc should pick a set of prefixes/namespaces that it's going to use¹ and lint against crates using reserved identifiers (unless considered stable), rather than choosing a prefix for the crate and using a lint to enforce that the crate uses that prefix.

In short, restricting crates to a specific prefix seems overly restrictive (prevents sharing) and doesn't really address intercrate isolation (the outer crate needs to know the inlined crates' --html-in-header usage to provide it, or the inlined docs will degrade without it). It seems reasonable to just rely on convention for intercrate cooperation. I wrote overly many words on this over on irlo.

On the other hand, a crate (or package) name prefix is still a good convention, so it potentially makes sense for both lints to exist separately. Being separate means a crate can still get assistance with staying out of rustdocs's way without getting hounded for using a different prefix (e.g. another crate by the same authors).

Footnotes

1. A reasonable set could be doc-*, rust-*, rustdoc-*, keyword-* for all Rust keywords, and any unprefixed names (names without - or _). Some kebab-case identifiers in use by rustdoc would need to change, but organization something like this could also help serve to visually distinguish what identifiers are stable and can be relied on by users from what identifiers are unstable implementation details and allowed to change. ↩

[jyn514]

I like that idea :) if we separate the lints, we could make the first (don't use rustdoc's prefix) a future-incompat lint which always warns, and the second (use a crate prefix) allow-by-default (or warn-by-default, but without being a future-incompat lint).

[jyn514]

@notriddle I don't have time to review 800 lines of changed code, sorry. If there's something specific you want feedback I might have time for that.

[notriddle]

@jyn514

Answer the questions in #106603 (comment) and proofread the new docs in how-to-write-documentation.md, please?

For the actual code review, let's re-roll the dice:

r? rustdoc

[GuillaumeGomez]

Overall this looks great! Just a small nit and it's all good code-wise for me. However, in this case, I'd still prefer to go through FCP so all the team can at least agree with this (the insta-stable part is important imo).

[GuillaumeGomez]

Then please start the FCP whenever it's ready for you.

[jyn514]

1. Right now, it separates the crate prefix from the rest of the identifier with _. This might not be the best choice.
2. This lint is being landed insta-stable. Is that okay?
3. Is crate name the right choice for the prefix?

1. I think we should suggest - as the separator, not _, since it's invalid in a crate name and therefore unambiguous. https://internals.rust-lang.org/t/proposed-lint-rustdoc-unprefixed-html-id/18099/11?u=jyn514
2. Yes :) I have a more detailed rationale in https://internals.rust-lang.org/t/proposed-lint-rustdoc-unprefixed-html-id/18099/8?u=jyn514
3. It seems reasonable but also I like @kpreid's idea in https://internals.rust-lang.org/t/proposed-lint-rustdoc-unprefixed-html-id/18099/13?u=jyn514 of having rustdoc add a prefix automatically.

[jyn514]

Do we have plans to enforce that at some point? It would be helpful for rust-lang/docs.rs#167, I think.

cc @rust-lang/docs-rs

[notriddle]

This bullet point was really only intended to address scripts and styles that actually modified rustdoc's UI. A one-off script that only modifies things in your own doc probably should be part of the doc comment so that it gets inline along with its DOM.

The thing that actually makes solid recommendations tough is code like KaTeX. It doesn't modify rustdoc's UI (so it can probably be safely inlined across crates), but it also isn't a one-off (so it probably shouldn't be included in the doc comment).

CC: https://internals.rust-lang.org/t/proposed-lint-rustdoc-unprefixed-html-id/18099/15?u=notriddle