rustdoc: Generate the documentation for one module on one page instead of several pages

[kud1ing]

Browsing the documentation for functions/structs foo, bar and baz currently involves a lot of clicks (click on foo, go back, click on bar, go back, click on baz).

Other language communities provide one documentation per module with "jumpable" links/anchors. Examples

• D: http://dlang.org/phobos/std_base64.html
• Go: http://golang.org/pkg/compress/zlib/

[alexcrichton]

I talked with @Seldaek on IRC (he headed up the design of the new pages), and the conclusion we reached was that it's probably not so bad the way it is now. It's true that there are more clicks, but we do have a search bar and a sidebar navigation to find things.

Basically, if it looks like the majority opinion is that it needs more content per page, then we should do that, otherwise it may be worth sticking to what exists (or at least this is my best summary).

[kud1ing]

If we had documented every module completely on one page each, we could provide both functionalities: the current "jump to definition" and the suggested "glanze at everything at once".

What would would be your reasons for moving the definitions back to separate pages? Page loading time?

I think truly finding out what the majority perceives will be difficult (measuring samples and overcoming sampling bias).
If we use "not a lot people complain about it" for a measurement substitute and we take Go and D communities for an approximation of the Rust community, we should switch to "everything on one page".

[Seldaek]

@kud1ing First of all I have to say that it is probably a very subjective thing, so I don't expect everyone to agree with me on this, and I don't expect I will be able to convince you, but I will try to explain my point of view at least.

I recognize the small issue of navigating from item to item, sure it can be a bit easier to scroll through the whole page, but on the other hand if you want to get back to the list of links on top you also have to hit "back" in some form, so the benefit isn't so huge compared to individual pages.

On the other hand, the benefits I see to individual pages are:

• more focus on what you're currently looking at, it's not lost in a sea of definitions.
• once the docs are (hopefully) a bit more complete and contain examples etc for most things, one individual element page will be already pretty long, and having it all in one will make it pretty much impossible to easily scan through I think.
• shorter pages so the sidebar/list of neighbors usually stays in focus or near focus. On your D docs example for example once you scroll you quickly get very far from useful sidebar links.
• less intimidating and confusing pages (kind of goes together with focus). That might be completely subjective, but I really find it easier to navigate through sidebar links to neighbor elements, or via the linked types (which is now much better. most things were not linked previously, forcing you to navigate by hand).

So all in all, I think between search and sidebar and type hyperlinks you have a lot more options to navigate easily and I find this superior to smashing everything on one page because navigation is hard. I just hope you'll give it a chance and hopefully see it's also a good model, but if ultimately most people dislike it we can obviously go back, it's not the hardest thing to change.

[kud1ing]

I agree this is subjective.
Your points a) and b) are valid, but to me not that strong. I think c) and d) can be solved by providing the function TOC in the sidebar and using CSS like in http://getbootstrap.com/getting-started/

Discoverability suffers currently, which is important for people new to Rust, and i think this is not subjective.
Take for example http://static.rust-lang.org/doc/master/std/ascii/index.html
What can you do with ASCII strings? You have to click on all of the 6 trait sublinks to discover the available methods and then you need to keep them either in your head or in browser tabs/windows.

[kud1ing]

Maybe we can agree on providing both views:

1. a brief overview of all definitions
2. a dedicated detail pages for each definition, including examples

[Seldaek]

Regarding the ascii example, in theory going to http://static.rust-lang.org/doc/master/std/ascii/struct.Ascii.html should list everything you can do with it. AsciiStr methods aren't listed for example, but that's a bug IMO. The AsciiStr page lists impl<'self> AsciiStr for &'self [Ascii] as an implementor, so ideally it should show up on the Ascii page. It's maybe not trivial to fix though.

I was a newcomer recently and still am in many ways, but I found the long pages pretty awful for discoverability, I always got lost in the long lists of similar sounding functions and various impls. That's why I started working on the new docs, and put a focus on links & search which I think allow discoverability much more than "oh I found this by chance". If I want to find something I usually have a remote idea of how it could be called, but I don't necessarily know in which module it could be.

[kud1ing]

I appreciate you hard work, thanks.

[Seldaek]

BTW I'm not opposing it on principle, and ultimately I don't really have a final say in this anyway. I'd just like to give it some time and see because I feel it's something that is bound to trigger resistance when it changes but people will hopefully grow used to it (and maybe even like it). Maybe I'm wrong though :)

As for the "can't we get both?", maybe. I just don't see how to make it happen sanely, but if someone has a concrete idea and can show a mockup (html or a piece of paper I don't mind) then I'd be happy to discuss it further.

[kud1ing]

Today i tried to find out using http://static.rust-lang.org/doc/master/std/str/index.html whether len() for str returns number of bytes or characters/code points. A simple task. But it really takes long, because there is no overview of the methods/functions which are defined per type.

[huonw]

@kud1ing this issue wouldn't actually fix that; it's mainly because of #10114 (since there's no page that lists all the traits that &str implements, they're only listed on the individual trait pages) and partly because of #6065 (although not for this specific case, just methods from traits like StrSlice).

[kud1ing]

@huonw: Those need to be fixed for this special use case, i agree. In general, i find it unfortunate that one needs to know in advance how/where a functionality is implemented (which trait). I think doucmentation would be more usable when all functionality would be presented at once.

[huonw]

Yes, that is exactly what #10114 covers, if that was implemented then &str would list all its methods and trait implementations on one page (including Container), like, for example, Option does.

This issue wouldn't actually fix the problems with built-in types, since a trait implementation is associated with the trait and the type, not the module in which it is implemented and so a page listing the entire contents of std::str would not (with the current behaviour) list the traits that &str implements.

[treeman]

Visiting for triage. There is a related proposal over at discuss.

[alexcrichton]

This is quite an old bug at this point, and I believe that rustdoc's design has changed pretty radically in the interim, so I'm going to close for now.