Add an option to allow rustdoc to list modules by appearance

The `--sort-modules-by-appearance` option will list modules in the
order that they appear in the source, rather than sorting them
alphabetically (as is the default). This resolves #8552.

src/librustdoc/html/render.rs

@@ -129,6 +129,9 @@ pub struct SharedContext {
     /// 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>>,
+    /// 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,
 }
 
 impl SharedContext {
@@ -491,7 +494,8 @@ pub fn run(mut krate: clean::Crate,
            passes: FxHashSet<String>,
            css_file_extension: Option<PathBuf>,
            renderinfo: RenderInfo,
-           render_type: RenderType) -> Result<(), Error> {
+           render_type: RenderType,
+           sort_modules_alphabetically: bool) -> Result<(), Error> {
     let src_root = match krate.src {
         FileName::Real(ref p) => match p.parent() {
             Some(p) => p.to_path_buf(),
@@ -514,6 +518,7 @@ pub fn run(mut krate: clean::Crate,
         css_file_extension: css_file_extension.clone(),
         markdown_warnings: RefCell::new(vec![]),
         created_dirs: RefCell::new(FxHashSet()),
+        sort_modules_alphabetically,
     };
 
     // If user passed in `--playground-url` arg, we fill in crate name here
@@ -1654,8 +1659,10 @@ impl Context {
                 .push((myname, Some(plain_summary_line(item.doc_value()))));
         }
 
-        for (_, items) in &mut map {
-            items.sort();
+        if self.shared.sort_modules_alphabetically {
+            for (_, items) in &mut map {
+                items.sort();
+            }
         }
         map
     }
@@ -2013,7 +2020,9 @@ fn item_module(w: &mut fmt::Formatter, cx: &Context,
         name_key(lhs).cmp(&name_key(rhs))
     }
 
-    indices.sort_by(|&i1, &i2| cmp(&items[i1], &items[i2], i1, i2));
+    if cx.shared.sort_modules_alphabetically {
+        indices.sort_by(|&i1, &i2| cmp(&items[i1], &items[i2], i1, i2));
+    }
     // This call is to remove reexport duplicates in cases such as:
     //
     // ```

src/librustdoc/lib.rs

@@ -253,6 +253,9 @@ pub fn opts() -> Vec<RustcOptGroup> {
         unstable("linker", |o| {
             o.optopt("", "linker", "linker used for building executable test code", "PATH")
         }),
+        unstable("sort-modules-by-appearance", |o| {
+            o.optflag("", "sort-modules-by-appearance", "sort modules by where they appear in the program, rather than alphabetically")
+        }),
     ]
 }
 
@@ -369,6 +372,7 @@ pub fn main_args(args: &[String]) -> isize {
     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);
+    let sort_modules_alphabetically = !matches.opt_present("sort-modules-by-appearance");
 
     match (should_test, markdown_input) {
         (true, true) => {
@@ -398,7 +402,8 @@ pub fn main_args(args: &[String]) -> isize {
                                   passes.into_iter().collect(),
                                   css_file_extension,
                                   renderinfo,
-                                  render_type)
+                                  render_type,
+                                  sort_modules_alphabetically)
                     .expect("failed to generate documentation");
                 0
             }