Rust: 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 https://github.com/rust-lang/rust/issues/71912#issuecomment-680097427: 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.

[GuillaumeGomez]

So you would want to include a breaking change for something stable even before 1.0? You'd need very strong reasons for it to be done and I'm really not convinced...

[RalfJung]

No we don't need a breaking change -- as @bluss wrote above, reasonably stable URLs already exist: https://doc.rust-lang.org/stable/std/mem/ManuallyDrop.t.html
But nobody knows about them because they are not used by default. So all it would take is swap the role of ManuallyDrop.t.html and struct.ManuallyDrop.html, making the latter a redirect and the former the target of all the automatically generated links.

[GuillaumeGomez]

Well, we kinda want to remove this URL format since a while. It's still there because it's being used by RLS iirc. Also, this would be a regression in my point of view considering you lose information. And since it's not the default URL format, it's definitely a breaking change.

[jyn514]

So you would want to include a breaking change for something stable

The point of discussion IMO is whether or not it _is_ stable. Currently, it's stable with respect to _rustdoc_ versions, but not with respect to the code being documented. Either

a) The file names should be predictable across versions being documented, in which case we should recommend ManuallyDrop.t.html, or
b) The file names are unstable and no one should depend on them, in which case we should change them every release so people don't depend on them by accident.

The current middle ground is sort of the worst of both worlds because it _looks_ like it's stable, but can break for changes that do not break semver.

[RalfJung]

The information you lose is not semver-stable and irrelevant for API consumers. It's like having the line number in the URL -- sure that would be more inforamtion, but it's not good information to have in the URL. That's what this issue is all about -- please consult the arguments given above.

Also, how is this a breaking change if it doesn't break anything? All existing URLs keep working.

[RalfJung]

IMO the question is quite simple at a fundamental level -- what does it take to uniquely identify an item in Rust (assuming you already know the crate it is in)? You need its name, its full module path, and its "kind" -- which can be value, type, or macro. And that's it. So this information should be sufficient to construct a URL, and no other information should be contained in the URL. After all, a "Uniform Resource Locator" is all about being able to locate resources, such as the documentation about items in Rust, in a uniform and consistent way.

[jyn514]

@RalfJung what do you propose we do about all the existing URLs that point to enum.ManuallyUninit.html? Should we generate redirects for _all_ pages in the type namespace? That seems like it would bloat the size of the docs quite a bit. But if we don't do that, then the URLs are still broken even if we make union.ManuallyUninit.html a redirect.

[RalfJung]

If my understanding is correct, currently we generate two pages for every type:

• [enum|struct|union].$name.html is the main page with all the fields and methods and stuff
• $name.t.html redirects to the above.

What I am proposing is to swap the role of these two files, so every existing link keeps working:

• $name.t.html is the main page with all the fields and methods and stuff
• [enum|struct|union].$name.html redirects to the above.

This cannot break any link that currently works. It means changing e.g. union to enum still breaks people that use the "wrong" (deprecated) union.$name.html, but that's certainly better than not having the union.$name.html redirect! Currently we break all links on a union -> enum change; with the new scheme we only break old links -- but new links that people set will go to the .t.html page. So, I'd say this is a strict improvement over the status quo.

[jyn514]

I'm happy with that. It doesn't fix the existing links to union.ManuallyDrop.html, but it encourages good practice for future links without being too much of a burden on rustdoc.

[RalfJung]

(I am not sure what ManuallyInit is. ManuallyDrop changed from union to struct, so if you mean the existing links to union.ManuallyDrop.html then I agree.)

[jyn514]

I was actually thinking of MaybeUninit 😆 so not even close

[RalfJung]

MaybeUninit is a union and always was, so I don't think it is relevant here.^^

[ollie27]

The namespace based redirects were removed in #70563.

[jyn514]

It looks like that was mostly to fix wonky hash handling? The only comment about namespaces I see is https://github.com/rust-lang/rust/pull/70563#issuecomment-652653459:

We should also fully revert #35236 not just part of it.

Is there any reason _not_ to add the namespace redirects back?

[GuillaumeGomez]

Why would we want it? It's a duplication of the current system. We removed it to stop having to maintain it and therefore reduce the amount of code.

[jyn514]

The _entire issue_ is giving reasons why we would want it. https://github.com/rust-lang/rust/issues/55160#issuecomment-681083071 has a good summary.

[RalfJung]

Why would we want it?

Please read this issue.