Use `name.namespace.html` as the canonical URL, not `kind.name.html`

[scottmcm]

I just wanted to look at the ManuallyDrop docs again, and my browser helpfully remembered that it's at https://doc.rust-lang.org/std/mem/union.ManuallyDrop.html. But, despite the type being stable, that page no longer exists; it's now https://doc.rust-lang.org/std/mem/struct.ManuallyDrop.html.

Is the specific item kind actually important to have in the path? The namespace (type vs value vs ...) certainly is, but especially for things without public fields, making the struct-vs-union distinction so front-and-centre seems overall unhelpful.

[GuillaumeGomez]

For me it's a positive thing. I'd argue that you'd better not use direct URLs and just search or rustdoc links. The current URLs are clear and represent what they should.

[mikeyhew]

@GuillaumeGomez I disagree with that, I think that direct links to documentation are useful, their use should be encouraged, and we should avoid breaking them if possible.

Having the extra information of struct, enum or type in the URL is kind of nice too, but the other thing is that switching from the current URLs to new ones would result in a lot of links breaking, so maybe there is some way to use redirects instead? Like if you went to https://doc.rust-lang.org/std/mem/union.ManuallyDrop.html or https://doc.rust-lang.org/std/mem/type.ManuallyDrop.html it would redirect you to https://doc.rust-lang.org/std/mem/struct.ManuallyDrop.html.

[GuillaumeGomez]

I'm not sure we understood each other. To be clear: the current state of rustdoc URLs seems good and should be kept unless something way better is proposed.

[RalfJung]

I agree with the OP that encoding the "kind" of type in the URL seems suboptimal. Rust has three namespaces (macro-level, fn/variable-level, type-level), so that needs to be encoded, but I see no good reason to encode more. type.ManuallyDrophtml has all the information needed to uniquely identify this type.

As another argument for why the current URLs are bad: this is one of the few cases where doing a semver-compatible change (changing a struct to an enum, for example) breaks docs links.

[nox]

Changing a struct to an enum isn't backwards-compatible (one can match against Struct { .. }), but I support removing the type kind from URLs, for the same rationale as in #64454.

[bluss]

We have a bunch of redirects that only focus on the namespace an item belongs to.

For example the URL https://doc.rust-lang.org/stable/std/mem/ManuallyDrop.t.html with "t" for type, will redirect to the correct place and I assume this URL was there before the struct/union switch happened. Only problem is that it's not the canonical URL. (And, it would be more ideal if we didn't have lots of extra redirect files, there are enough small files already in a rustdoc site).

[RalfJung]

@bluss wow, I had no idea these files even existed!

For use in rustc/libstd, if they should be useful we need a tidy pass that tells people to link to the "t" file instead of the "struct"/"enum"/"union" file.

[GuillaumeGomez]

It was for RLS iirc. Not sure if removing it is fine but I'd like to remove it.

[jyn514]

I disagree with that, I think that direct links to documentation are useful, their use should be encouraged, and we should avoid breaking them if possible.

I have the same comment as in #71912 (comment): direct links should use intra-doc links, the links rustdoc generates are not stable.

[RalfJung]

@jyn514 so say I am writing a blog post and mentioning some Rust types whose docs I want to reference. Obviously my site generator does not support intra-doc links. What do you propose I do?

This is something people already do -- anything that has a URL has people link to it. It's what makes the web so amazing. Please don't break that.

[GuillaumeGomez]

URLs are stable, the DOM content isn't. However, since you always use a specific version of a crate, you can just link to the element of this specific version of the crate on docs.rs.

[RalfJung]

URLs are not stable when a struct becomes an enum (which otherwise is semver-compatible if the struct had a private field).

[GuillaumeGomez]

Then that's on the crate owner, not on rustdoc. We the URLs are defined as [type].[type name].html. If you change an item's type, then you change the URL. It's predictable. But again: always reference to a specific version of a crate and that shouldn't be an issue.

[RalfJung]

The entire point of this issue is that there is no good reason to include struct vs union in the URL. The "item type" of all structs, unions and enums should be just type.

It's predictable, sure, but that does not make it sensible.