Rollup merge of rust-lang#46787 - varkor:contrib-6, r=QuietMisdreavus

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 rust-lang#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,10 @@ 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 +373,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 +403,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
  }

src/test/rustdoc/sort-modules-by-appearance.rs

@@ -0,0 +1,23 @@
+// 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"'