Rollup merge of rust-lang#49451 - QuietMisdreavus:epoch-doctests, r=GuillaumeGomez

rustdoc: add an --edition flag to compile docs/doctests with a certain edition

To correspond with the 2018 edition, this adds a (currently unstable) `--edition` flag to rustdoc that makes it compile crates and doctests with the given edition. Once this lands, Cargo should be updated to pass this flag when the edition configuration option is given.

Author: Mark-Simulacrum

src/doc/rustdoc/src/unstable-features.md

@@ -348,6 +348,19 @@ details.
 
 [issue-display-warnings]: https://github.com/rust-lang/rust/issues/41574
 
+### `--edition`: control the edition of docs and doctests
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -Z unstable-options --edition 2018
+$ rustdoc --test src/lib.rs -Z unstable-options --edition 2018
+```
+
+This flag allows rustdoc to treat your rust code as the given edition. It will compile doctests with
+the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
+(the first edition).
+
 ### `-Z force-unstable-if-unmarked`
 
 Using this flag looks like this:

src/librustdoc/core.rs

@@ -26,6 +26,7 @@ use rustc_back::target::TargetTriple;
 
 use syntax::ast::NodeId;
 use syntax::codemap;
+use syntax::edition::Edition;
 use syntax::feature_gate::UnstableFeatures;
 use errors;
 use errors::emitter::ColorConfig;
@@ -123,7 +124,8 @@ pub fn run_core(search_paths: SearchPaths,
                 maybe_sysroot: Option<PathBuf>,
                 allow_warnings: bool,
                 crate_name: Option<String>,
-                force_unstable_if_unmarked: bool) -> (clean::Crate, RenderInfo)
+                force_unstable_if_unmarked: bool,
+                edition: Edition) -> (clean::Crate, RenderInfo)
 {
     // Parse, resolve, and typecheck the given crate.
 
@@ -148,6 +150,7 @@ pub fn run_core(search_paths: SearchPaths,
         actually_rustdoc: true,
         debugging_opts: config::DebuggingOptions {
             force_unstable_if_unmarked,
+            edition,
             ..config::basic_debugging_options()
         },
         ..config::basic_options().clone()

src/librustdoc/lib.rs

@@ -61,6 +61,7 @@ use std::path::{Path, PathBuf};
 use std::process;
 use std::sync::mpsc::channel;
 
+use syntax::edition::Edition;
 use externalfiles::ExternalHtml;
 use rustc::session::search_paths::SearchPaths;
 use rustc::session::config::{ErrorOutputType, RustcOptGroup, nightly_options, Externs};
@@ -271,6 +272,11 @@ pub fn opts() -> Vec<RustcOptGroup> {
                       \"light-suffix.css\"",
                      "PATH")
         }),
+        unstable("edition", |o| {
+            o.optopt("", "edition",
+                     "edition to use when compiling rust code (default: 2015)",
+                     "EDITION")
+        }),
     ]
 }
 
@@ -429,14 +435,23 @@ pub fn main_args(args: &[String]) -> isize {
     let sort_modules_alphabetically = !matches.opt_present("sort-modules-by-appearance");
     let resource_suffix = matches.opt_str("resource-suffix");
 
+    let edition = matches.opt_str("edition").unwrap_or("2015".to_string());
+    let edition = match edition.parse() {
+        Ok(e) => e,
+        Err(_) => {
+            print_error("could not parse edition");
+            return 1;
+        }
+    };
+
     match (should_test, markdown_input) {
         (true, true) => {
             return markdown::test(input, cfgs, libs, externs, test_args, maybe_sysroot,
-                                  display_warnings, linker)
+                                  display_warnings, linker, edition)
         }
         (true, false) => {
             return test::run(Path::new(input), cfgs, libs, externs, test_args, crate_name,
-                             maybe_sysroot, display_warnings, linker)
+                             maybe_sysroot, display_warnings, linker, edition)
         }
         (false, true) => return markdown::render(Path::new(input),
                                                  output.unwrap_or(PathBuf::from("doc")),
@@ -446,7 +461,7 @@ pub fn main_args(args: &[String]) -> isize {
     }
 
     let output_format = matches.opt_str("w");
-    let res = acquire_input(PathBuf::from(input), externs, &matches, move |out| {
+    let res = acquire_input(PathBuf::from(input), externs, edition, &matches, move |out| {
         let Output { krate, passes, renderinfo } = out;
         info!("going to format");
         match output_format.as_ref().map(|s| &**s) {
@@ -487,14 +502,15 @@ fn print_error<T>(error_message: T) where T: Display {
 /// and files and then generates the necessary rustdoc output for formatting.
 fn acquire_input<R, F>(input: PathBuf,
                        externs: Externs,
+                       edition: Edition,
                        matches: &getopts::Matches,
                        f: F)
                        -> Result<R, String>
 where R: 'static + Send, F: 'static + Send + FnOnce(Output) -> R {
     match matches.opt_str("r").as_ref().map(|s| &**s) {
-        Some("rust") => Ok(rust_input(input, externs, matches, f)),
+        Some("rust") => Ok(rust_input(input, externs, edition, matches, f)),
         Some(s) => Err(format!("unknown input format: {}", s)),
-        None => Ok(rust_input(input, externs, matches, f))
+        None => Ok(rust_input(input, externs, edition, matches, f))
     }
 }
 
@@ -520,8 +536,14 @@ fn parse_externs(matches: &getopts::Matches) -> Result<Externs, String> {
 /// generated from the cleaned AST of the crate.
 ///
 /// This form of input will run all of the plug/cleaning passes
-fn rust_input<R, F>(cratefile: PathBuf, externs: Externs, matches: &getopts::Matches, f: F) -> R
-where R: 'static + Send, F: 'static + Send + FnOnce(Output) -> R {
+fn rust_input<R, F>(cratefile: PathBuf,
+                    externs: Externs,
+                    edition: Edition,
+                    matches: &getopts::Matches,
+                    f: F) -> R
+where R: 'static + Send,
+      F: 'static + Send + FnOnce(Output) -> R
+{
     let mut default_passes = !matches.opt_present("no-defaults");
     let mut passes = matches.opt_strs("passes");
     let mut plugins = matches.opt_strs("plugins");
@@ -570,7 +592,7 @@ where R: 'static + Send, F: 'static + Send + FnOnce(Output) -> R {
         let (mut krate, renderinfo) =
             core::run_core(paths, cfgs, externs, Input::File(cratefile), triple, maybe_sysroot,
                            display_warnings, crate_name.clone(),
-                           force_unstable_if_unmarked);
+                           force_unstable_if_unmarked, edition);
 
         info!("finished with rustc");
 

src/librustdoc/markdown.rs

@@ -18,6 +18,7 @@ use testing;
 use rustc::session::search_paths::SearchPaths;
 use rustc::session::config::Externs;
 use syntax::codemap::DUMMY_SP;
+use syntax::edition::Edition;
 
 use externalfiles::{ExternalHtml, LoadStringError, load_string};
 
@@ -139,7 +140,7 @@ pub fn render(input: &Path, mut output: PathBuf, matches: &getopts::Matches,
 /// Run any tests/code examples in the markdown file `input`.
 pub fn test(input: &str, cfgs: Vec<String>, libs: SearchPaths, externs: Externs,
             mut test_args: Vec<String>, maybe_sysroot: Option<PathBuf>,
-            display_warnings: bool, linker: Option<PathBuf>) -> isize {
+            display_warnings: bool, linker: Option<PathBuf>, edition: Edition) -> isize {
     let input_str = match load_string(input) {
         Ok(s) => s,
         Err(LoadStringError::ReadFail) => return 1,
@@ -151,7 +152,7 @@ pub fn test(input: &str, cfgs: Vec<String>, libs: SearchPaths, externs: Externs,
     let mut collector = Collector::new(input.to_owned(), cfgs, libs, externs,
                                        true, opts, maybe_sysroot, None,
                                        Some(PathBuf::from(input)),
-                                       linker);
+                                       linker, edition);
     find_testable_code(&input_str, &mut collector, DUMMY_SP, None);
     test_args.insert(0, "rustdoctest".to_string());
     testing::test_main(&test_args, collector.tests,

src/librustdoc/test.rs

@@ -34,6 +34,7 @@ use rustc_metadata::cstore::CStore;
 use rustc_resolve::MakeGlobMap;
 use syntax::ast;
 use syntax::codemap::CodeMap;
+use syntax::edition::Edition;
 use syntax::feature_gate::UnstableFeatures;
 use syntax::with_globals;
 use syntax_pos::{BytePos, DUMMY_SP, Pos, Span, FileName};
@@ -57,7 +58,8 @@ pub fn run(input_path: &Path,
            crate_name: Option<String>,
            maybe_sysroot: Option<PathBuf>,
            display_warnings: bool,
-           linker: Option<PathBuf>)
+           linker: Option<PathBuf>,
+           edition: Edition)
            -> isize {
     let input = config::Input::File(input_path.to_owned());
 
@@ -70,6 +72,10 @@ pub fn run(input_path: &Path,
         unstable_features: UnstableFeatures::from_environment(),
         lint_cap: Some(::rustc::lint::Level::Allow),
         actually_rustdoc: true,
+        debugging_opts: config::DebuggingOptions {
+            edition,
+            ..config::basic_debugging_options()
+        },
         ..config::basic_options().clone()
     };
 
@@ -117,7 +123,8 @@ pub fn run(input_path: &Path,
                                        maybe_sysroot,
                                        Some(codemap),
                                        None,
-                                       linker);
+                                       linker,
+                                       edition);
 
     {
         let map = hir::map::map_crate(&sess, &cstore, &mut hir_forest, &defs);
@@ -177,8 +184,7 @@ fn run_test(test: &str, cratename: &str, filename: &FileName, line: usize,
             externs: Externs,
             should_panic: bool, no_run: bool, as_test_harness: bool,
             compile_fail: bool, mut error_codes: Vec<String>, opts: &TestOptions,
-            maybe_sysroot: Option<PathBuf>,
-            linker: Option<PathBuf>) {
+            maybe_sysroot: Option<PathBuf>, linker: Option<PathBuf>, edition: Edition) {
     // the test harness wants its own `main` & top level functions, so
     // never wrap the test in `fn main() { ... }`
     let (test, line_offset) = make_test(test, Some(cratename), as_test_harness, opts);
@@ -204,6 +210,10 @@ fn run_test(test: &str, cratename: &str, filename: &FileName, line: usize,
         },
         test: as_test_harness,
         unstable_features: UnstableFeatures::from_environment(),
+        debugging_opts: config::DebuggingOptions {
+            edition,
+            ..config::basic_debugging_options()
+        },
         ..config::basic_options().clone()
     };
 
@@ -465,13 +475,14 @@ pub struct Collector {
     codemap: Option<Lrc<CodeMap>>,
     filename: Option<PathBuf>,
     linker: Option<PathBuf>,
+    edition: Edition,
 }
 
 impl Collector {
     pub fn new(cratename: String, cfgs: Vec<String>, libs: SearchPaths, externs: Externs,
                use_headers: bool, opts: TestOptions, maybe_sysroot: Option<PathBuf>,
                codemap: Option<Lrc<CodeMap>>, filename: Option<PathBuf>,
-               linker: Option<PathBuf>) -> Collector {
+               linker: Option<PathBuf>, edition: Edition) -> Collector {
         Collector {
             tests: Vec::new(),
             names: Vec::new(),
@@ -486,6 +497,7 @@ impl Collector {
             codemap,
             filename,
             linker,
+            edition,
         }
     }
 
@@ -505,6 +517,7 @@ impl Collector {
         let opts = self.opts.clone();
         let maybe_sysroot = self.maybe_sysroot.clone();
         let linker = self.linker.clone();
+        let edition = self.edition;
         debug!("Creating test {}: {}", name, test);
         self.tests.push(testing::TestDescAndFn {
             desc: testing::TestDesc {
@@ -535,7 +548,8 @@ impl Collector {
                                  error_codes,
                                  &opts,
                                  maybe_sysroot,
-                                 linker)
+                                 linker,
+                                 edition)
                     }))
                 } {
                     Ok(()) => (),