Change:
Instead it should use the order that appear in the crate file. Even better, it should allow adding section headers (with a description) between them. Hypothetically: And get something like this: 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.
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.
Yeah, I'm going to vote "alphabetical".
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".
Agreed. Can someone rename the title?
Rename done.
Visiting for triage. Minor, but still an issue.
Triage, still listed alphabetically. Here's a sample source file: !

Discussion:
/// The directories that have already been created in this doc run. Used to reduce the number /// of spurious `create_dir_all` calls. pub created_dirs: RefCell<FxHashSet<PathBuf>>, <ins> /// This flag indicates whether listings of modules (in the side bar and documentation itself) /// should be ordered alphabetically or in order of appearance (in the source code). pub sort_modules_alphabetically: bool, </ins> } impl SharedContext {

passes: FxHashSet<String>, css_file_extension: Option<PathBuf>, renderinfo: RenderInfo, <del> render_type: RenderType) -> Result<(), Error> { </del> <ins> render_type: RenderType, sort_modules_alphabetically: bool) -> Result<(), Error> { </ins> let src_root = match krate.src { FileName::Real(ref p) => match p.parent() { Some(p) => p.to_path_buf(),

css_file_extension: css_file_extension.clone(), markdown_warnings: RefCell::new(vec![]), created_dirs: RefCell::new(FxHashSet()), <ins> sort_modules_alphabetically, </ins> }; // If user passed in `--playground-url` arg, we fill in crate name here

.push((myname, Some(plain_summary_line(item.doc_value())))); } <del> for (_, items) in &mut map { items.sort(); </del> <ins> if self.shared.sort_modules_alphabetically { for (_, items) in &mut map { items.sort(); } </ins> } map }

name_key(lhs).cmp(&name_key(rhs)) } <del> indices.sort_by(|&i1, &i2| cmp(&items[i1], &items[i2], i1, i2)); </del> <ins> if cx.shared.sort_modules_alphabetically { indices.sort_by(|&i1, &i2| cmp(&items[i1], &items[i2], i1, i2)); } </ins> // This call is to remove reexport duplicates in cases such as: // // ```

unstable("linker", |o| { o.optopt("", "linker", "linker used for building executable test code", "PATH") }), <ins> unstable("sort-modules-by-appearance", |o| { o.optflag("", "sort-modules-by-appearance", "sort modules by where they appear in the  program, rather than alphabetically") }), </ins> ] }

let maybe_sysroot = matches.opt_str("sysroot").map(PathBuf::from); let display_warnings = matches.opt_present("display-warnings"); let linker = matches.opt_str("linker").map(PathBuf::from); <ins> let sort_modules_alphabetically = !matches.opt_present("sort-modules-by-appearance"); </ins> match (should_test, markdown_input) { (true, true) => {

passes.into_iter().collect(), css_file_extension, renderinfo, <del> render_type) </del> <ins> render_type, sort_modules_alphabetically) </ins> .expect("failed to generate documentation"); 0 }

<ins> // Copyright 2017 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. // Tests the rustdoc --sort-modules-by-appearance option, that allows module declarations to appear // in the order they are declared in the source code, rather than only alphabetically. // compile-flags: -Z unstable-options --sort-modules-by-appearance pub mod module_b {} pub mod module_c {} pub mod module_a {} // @matches 'sort_modules_by_appearance/index.html' '(?s)module_b.*module_c.*module_a' // @matches 'sort_modules_by_appearance/sidebar-items.js' '"module_b".*"module_c".*"module_a"' </ins>