Pre-RFC: Stable rustdoc URLs

language design
7

After thinking mode over more, I think the only reasonable cases of a semver-compatible changes are:

  • switching between struct, enum, union, and type.
  • switching whether an item is a pub use or the original.
  • MAYBE converting a static to a const, if your documentation warned users not to rely on it to have a single address.

For the other conversions:

  • You essentially can't convert between modules and types/traits, as above.
  • You can't convert a trait to anything else (someone could have used it as a bound).
  • You can only convert a type to a trait if you're willing to make your users use deprecated trait objects without dyn.
  • You can't convert a function to a const or static (someone might have called it).
  • You can't convert a const to a static (someone might have used it in a const context).
  • …I don't technically see why you couldn't convert a const or static to a function, but just like with the "empty module to enum" case, any const or static that could be converted to a function would be useless.

This means we can mostly keep the current URLs, only unifying struct, enum, union, and type. That should address the main issue, while avoiding the confusion of "Why is my fn item written with a v?"

So my proposal would be:

  • struct, enum, union, and type all use the format type.[Name].html. (With redirects from [kind].[Name].html for backwards compatibility.).
  • MAYBE unify const and static the same way (to value.[NAME].html, I guess?)
  • pub use declarations will generate redirects.
  • All other URLs remain the same as at present.

As for the name collision issue… It turns out I was wrong above, we can't just mangle names with nonstandard capitalization, because Took and ToOk are both perfectly reasonable CamelCase names. So it's either mangle all CamelCase names ever, or only mangle names in case of collisions (which sacrifices URL stability in that case, because it means that when you add a colliding name - which is a semver-compatible thing to do - you change the URL of the item that was there before). I'm guessing that "mangle all names ever" would be a nonstarter at this point, so it's just a question of – in the case of collisions, which would we rather sacrifice, "working correctly on Windows" or "having the URLs look normal and be stable"? I'd personally be inclined not to touch that decision in this RFC (and given that my proposal is slightly more limited than yours, it would probably cause a smaller increase in collisions)

1 Like