From 7104e8f7b4da1cfdbd82fa7c4f81ed31be22f95e Mon Sep 17 00:00:00 2001 From: varkor Date: Sun, 17 Dec 2017 15:22:50 +0000 Subject: [PATCH 1/3] 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 | 17 +++++++++++++---- src/librustdoc/lib.rs | 7 ++++++- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index 8ed35aa8f4396..9f981e97a762b 100644 --- a/src/librustdoc/html/render.rs +++ b/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>, + /// 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, css_file_extension: Option, 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: // // ``` diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 1cf71eca84681..1b0ff3a71d70e 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -253,6 +253,9 @@ pub fn opts() -> Vec { 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 } From c0ff8144c49bdcad19eaa9b9847a7ea9e008cfee Mon Sep 17 00:00:00 2001 From: varkor Date: Mon, 18 Dec 2017 19:52:45 +0000 Subject: [PATCH 2/3] Fix tidy issue --- src/librustdoc/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 1b0ff3a71d70e..7ebacdec1f0b2 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -254,7 +254,8 @@ pub fn opts() -> Vec { 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") + o.optflag("", "sort-modules-by-appearance", "sort modules by where they appear in the \ + program, rather than alphabetically") }), ] } From b3c6102be3752fa1b70cc5f9cf9903b13a4c3928 Mon Sep 17 00:00:00 2001 From: varkor Date: Tue, 19 Dec 2017 01:05:06 +0000 Subject: [PATCH 3/3] Add a test for `--sort-modules-by-appearance` --- .../rustdoc/sort-modules-by-appearance.rs | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 src/test/rustdoc/sort-modules-by-appearance.rs diff --git a/src/test/rustdoc/sort-modules-by-appearance.rs b/src/test/rustdoc/sort-modules-by-appearance.rs new file mode 100644 index 0000000000000..abffe6fb95b99 --- /dev/null +++ b/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 or the MIT license +// , 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"'