Rustdoc shouldn't list modules only alphabetically

[orenbenkiki]

Instead it should use the order that pub mod foo appear in the crate file. Even better, it should allow adding section headers (with a description) between them. Hypothetically:

/// Modules for foo-ing.
pub mod foo;

/// Modules for ba-ing. Ba-ing has several variants, all distinct from foo-ing.
pub mod bar;
pub mod baz;

And get something like this:

Modules

Modules for foo-ing

foo - Description of foo.

Modules for ba-ing

Ba-ing is distinct from foo-ing.

bar - Description for bar.
baz - Description for baz.

This would make both the source code and the documentation more accessible as the modules would be presented in a comprehensible order, with some description of each related group of modules.

Edit: Rename issue to reflect that this isn't an either-or. Alphabetical order is useful, but so is programmer-specified order (to make the code accessible for newcomers) and Rustdoc should support both - see the thread below.

[Seldaek]

Shouldn't related modules be nested in submodules rather than logically ordered in the source? Finding things in long non-ordered lists is a real pain.

[graydon]

Yeah, I'm going to vote "alphabetical".

[orenbenkiki]

Hmmm. I pretty sure I put a comment here, and now its gone. Strange. Anyway. Here it goes again.

Alphabetical order == random order. That's great when you know what you are looking for and just want to find it.

When coming to a new non-trivial code base, being presented the content in random order is just about the worst possible way to access it.

Nested modules allow us to group related modules together, and that's a good thing. If you have a long list of modules, certainly, group them. But this doesn't solve the problem. You now have a TOC where each level is randomized, which is still inaccessible.

Searching for a function or module by name is an important use case, sure. But being able to access a new code base is as important, if not more so.

Looking up a name in a short non-alphabetized list (at each level) isn't too hard, and one can always compensate for the lack of an alphabetical index by using ^F. Trying to understand a system presented in random order is next to impossible, and one can not compensate for the lack of a comprehensible order in a large system.

If there was a way to specify the order of the entries in each level, which we agree should only contain "a few" entries, then the TOC would become accessible. If one could even add a bit of annotation for each level, so much the better. The annotated TOC would serve as a very accessible way for a newcomer to understand the code base.

And, this doesn't rule out also generating an alphabetically sorted reference index, beside the TOC. All good books do both - a TOC in reasonable order and an index for looking up data by name. We shouldn't have to choose, we should be able to get both.

So, I misnamed the issue. It should be "Rustdoc shouldn't list modules only alphabetically".

[kud1ing]

We shouldn't have to choose, we should be able to get both.
So, I misnamed the issue. It should be "Rustdoc shouldn't list modules only alphabetically".

Agreed. Can someone rename the title?

[orenbenkiki]

Rename done.

[emberian]

Visiting for triage. Minor, but still an issue.

[steveklabnik]

Triage, still listed alphabetically. Here's a sample source file:

pub mod b {
    pub type B = i32;
}

pub mod a {
    pub type A = i32;
}