Stable Rustdoc URLs

[jyn514]

Rendered
Pre-RFC

cc @rust-lang/rustdoc

[danielhenrymantilla]

• Name.html for values
• t.Name.html for types
• m.Name.html for macros
  Rustdoc will continue to use directories (and index.html) for modules.

🤔 won't that conflict if someone were to define, for instance, fn index?
I guess the original v.Name.html did circumvent that issue too 😅

[jyn514]

You keep tearing holes in my plans!

Ok, the options are:

1. special case values named index to use v.index.html
2. always use the v prefix for values

Personally I prefer 2. but either would work I think.

[GuillaumeGomez]

@danielhenrymantilla I think that we should keep v.name.html for values for consistency with other URLs.

[GuillaumeGomez]

And I just thought, instead of "values", shouldn't we call them "items" instead? It seems more generic to me, meaning that v.name.html would therefore becomes i.name.hml. What do you think?

[jyn514]

shouldn't we call them "items" instead?

Items refers to anything that rustdoc links to, not just values. So for consistency we'd have to use it for types and macros as well, which breaks namespacing. So I think we should keep it as v.name.html.

[Manishearth]

And I just thought, instead of "values", shouldn't we call them "items" instead? It seems more generic to me, meaning that v.name.html would therefore becomes i.name.hml. What do you think?

Everything rustdoc documents at the top level is an item.

[chrysn]

If we want to make the URIs stable (which I appreciate) and change them one more time before we pledge not to any more, we should ensure they conform to the over 20 years old but still good guidelines on picking URIs, "Cool URIs don't change".

One of the points in there is not to expose file name extensions. One way of doing that which retains a static server's ability to come up with the right media type is to put items into own directories as well.

This would implicitly solve the index.html vs. const index problem and allow for

• Name/ for values
• t.Name/ for types
• m.Name/ for macros

[woshilapin]

at the cost of making them more confusing for traits

I'd say this same argument could be provided against the short version t.Trait.html too. What does even mean t. here? Unless I read the current RFC, it's going to be confusing too, isn't it?

It feels to me we could list the pros and cons for the short and the long version:

• pro-short: short URL, less typing
• cons-short: confusing
• pro-long: explicit
• cons-long: more typing, confusing

And about typing, I'm not even sure it's a valid argument for short or against long because most of it is going to be automated in RustDoc.

What was the rationale behind choosing the short version over the long version besides the supposed confusing aspect?

[jyn514]

t. is intentionally ambiguous - it means 'type namespace', but you could imagine it also meaning 'trait'. Like you said, it will be automated in rustdoc.

What benefits do you see for making it the long version instead?

[woshilapin]

Since the computer (aka RustDoc in this case) is doing it for me, I usually prefer long names because:

• I don't have to type them so length doesn't matter
• it is self-documented, meaning anyone who sees it can understand the prefix (whereas the short version is not as obvious)

[jyn514]

Hmm, do you think type.Trait.html is less confusing than t.Trait.html? @elidupree pointed that out as a drawback of the other approach in https://internals.rust-lang.org/t/pre-rfc-stable-rustdoc-urls/13099/15.

[woshilapin]

First of all, thank you to take the time trying to understand my position.

I do not think type.Trait.html is too confusing. But this is only my opinion.

My point is: if type.Trait.html is confusing, then I don't understand how t.Trait.html is less confusing since it does mean the same, just in an abbreviated way. And this is just a nice coincidence that the first letter of type happens to be the same as trait... but playing that card is only trumping people.

(please excuse if the tone is perceived too harsh, English not being my first language, I do not intend to be harsh 😄)

For me, I prefer long names for the same reason I put --output in a bash script instead of -o: both achieved the same functionality but for one of them, I don't have to go look the documentation to understand what it is (useful if I have to maintain that piece of code).

[jyn514]

Ok, I changed it back to type. @elidupree if you still have concerns please speak up :)

[elidupree]

I'll repeat what I said in the IRLO thread:

The scenario I'm imagining is that someone will be looking for a trait, click to the trait page, glance at the URL bar, think "oh wait, I was looking for a trait but I accidentally clicked to a type", and go back to look elsewhere for the trait.

This won't happen that often, but when it does, it's a sizable mental stumbling block for someone who is trying to just use the documentation as intended. The t.Trait.html naming scheme avoids this problem.

(Having separate type.Name.html and trait.Name.html entries would also avoid the problem, and I still think that would be a reasonable approach, since it's hard to imagine a scenario where you'd try to replace a type with a trait in a semver-compatible way. But if we're using the namespace-only approach, t. is preferable for this reason.)

[Manishearth]

I agree, most rust users aren't well aware of the namespaces

[jyn514]

One of the points in there is not to expose file name extensions. One way of doing that which retains a static server's ability to come up with the right media type is to put items into own directories as well

How will this interact with modules? Currently rustdoc uses directories only for modules, and it kind of needs that so it can nest things - in your proposal Name/ for values would conflict with Name/ for modules.

[chrysn]

in your proposal Name/ for values would conflict with Name/ for modules.

That's a conflict I did not think of -- so it wouldn't solve the bare-value-name issue, but with keeping the v. prefix,

• v.Name/ for values
• t.Name/ for types
• m.Name/ for macros
• Name/ for modules

would repair that. Dots are not legal in module names (even with r#). The conflict with index.html is traded with the conflict with submodules, and the solution that worked for index.html works for the submodules as well. Net result, it'll be only addressing the file extension point and not help anywhere else.

[jyn514]

Net result, it'll be only addressing the file extension point and not help anywhere else.

Hmm, in that case do you think it's worth making the directory structure much more nested? Rustdoc already gets some complaints that it generates too many files; this would make it generate just as many directories.

One of the points in there is not to expose file name extensions

I'm not sure this is too valuable for Rustdoc since it only exposes .html and changing to anything other than HTML would be a much larger breaking change (it would break all of docs.rs, for instance).

[chrysn]

generates too many files

I only know complaints of too many files from situations with too many directory entries; that wouldn't change.

only exposes .html

Granted, it hasn't changed in the 20 years time this guidance has been around. But it still cuts us some room in extensibility: If, say, localized documentation comes around, or graphical elements get added (like doxygen's call graphs), it makes it easier to put them somewhere without blowing up the above numbers. Besides the practical considerations, it more clearly expresses the intention of the URL ("the documentation of this module", and that it's in HTML is more a technical detail than a property of the thing), and last but not least looks shorter and cleaner :-)

TBH I wouldn't suggest this even at the stabilization of the URIs were it not for the path choices already being re-evaluated. There's guidance out there for how to name pages, and we're already renaming, so...

[jyn514]

I just realized that having separate directories will break relative links :/ currently most of the ecosystem uses see also [MyStruct][struct.MyStruct.html] and that would be a 404 under your new scheme, because every file would be in its own directory. So for that reason alone I think that might not be the best approach.

Intra-doc links would help with this, but that would require 100% of the ecosystem to be using intra-doc links for relative URLs which I don't think is realistic.

[est31]

This RFC only concerns the URL components relative to the crate root of the currently documented crate, right? Because currently there are a bunch of issues with cargo doc's choice of crate URLs, like e.g. rust-lang/rust#56169 . I presume it's not the intent to lock in the current behaviour?

[jyn514]

Correct, this is only about URLs relative to the crate root. It does not attempt to address rust-lang/rust#56169.

[Manishearth]

So, I've been thinking about this more, is there a reason why we need to unify everything into the namespaces? The existence of the three namespaces is not well understood by most rustaceans, and I'm not a fan of exposing it.

Can we get the same effects by just doing this for type? I.e. structs and enums all live at type.Foo.html, with redirects from struct.Foo.html and enum.Foo.html and union.Foo.html (whichever kind it is). As I understand it all other such prefixes are already unique and the library cannot be changed in a way that changes these without it being a breaking change (unlike changing a private struct to an enum).

[elidupree]

@Manishearth I made a similar proposal here: https://internals.rust-lang.org/t/pre-rfc-stable-rustdoc-urls/13099/7?u=elidupree

When I first started noticing rustdoc URLs, I was honestly a little confused about why it included "struct." in the URL at all, instead of just having the name. But some prefix is necessary because of the namespaces (e.g. because you can have both struct Q {} and const Q: i32 = 0; in the same module). So I do see the rationale for basing it on namespaces, because that's the minimal disambiguation needed.

I still think the greater amount of disambiguation is a reasonable proposal, but I'm not too attached to it.

[Manishearth]

Can we get the same effects by just doing this for type? I.e. structs and enums all live at type.Foo.html, with redirects from struct.Foo.html and enum.Foo.html and union.Foo.html (whichever kind it is). As I understand it all other such prefixes are already unique and the library cannot be changed in a way that changes these without it being a breaking change (unlike changing a private struct to an enum).

An added benefit of this is that we don't get inundiated with redirects. I sometimes open doc pages from the command line, so it's good to not have clutter.

[jyn514]

I'd still like to see this merged, but I'm not planning to follow up on any of the comments. Happy for someone else to pick it up.