Auto merge of rust-lang#38179 - michael-zapata:rf/harmonise_rustdoc_errors, r=GuillaumeGomez

feat(rustdoc): harmonise error messages

Based on unix tools wording, it follows a standard format: `program_name: context: error message`, potentially prompting the user to use the `--help` option.

This is clearly meant to trigger some discussion on rust-lang#38084, as messages still use `stdout` and `stderr` somewhat arbitrarily, and there are a few `error!()` calls as well.

Author: bors

Diff for: src/librustdoc/lib.rs

@@ -54,6 +54,9 @@ extern crate serialize as rustc_serialize; // used by deriving
 use std::collections::{BTreeMap, BTreeSet};
 use std::default::Default;
 use std::env;
+use std::fmt::Display;
+use std::io;
+use std::io::Write;
 use std::path::PathBuf;
 use std::process;
 use std::sync::mpsc::channel;
@@ -183,7 +186,7 @@ pub fn main_args(args: &[String]) -> isize {
     let matches = match getopts::getopts(&args[1..], &all_groups) {
         Ok(m) => m,
         Err(err) => {
-            println!("{}", err);
+            print_error(err);
             return 1;
         }
     };
@@ -211,11 +214,11 @@ pub fn main_args(args: &[String]) -> isize {
     }
 
     if matches.free.is_empty() {
-        println!("expected an input file to act on");
+        print_error("missing file operand");
         return 1;
     }
     if matches.free.len() > 1 {
-        println!("only one input file may be specified");
+        print_error("too many file operands");
         return 1;
     }
     let input = &matches.free[0];
@@ -227,7 +230,7 @@ pub fn main_args(args: &[String]) -> isize {
     let externs = match parse_externs(&matches) {
         Ok(ex) => ex,
         Err(err) => {
-            println!("{}", err);
+            print_error(err);
             return 1;
         }
     };
@@ -247,14 +250,16 @@ pub fn main_args(args: &[String]) -> isize {
 
     if let Some(ref p) = css_file_extension {
         if !p.is_file() {
-            println!("{}", "--extend-css option must take a css file as input");
+            writeln!(
+                &mut io::stderr(),
+                "rustdoc: option --extend-css argument must be a file."
+            ).unwrap();
             return 1;
         }
     }
 
     let external_html = match ExternalHtml::load(
-            &matches.opt_strs("html-in-header"),
-            &matches.opt_strs("html-before-content"),
+            &matches.opt_strs("html-in-header"), &matches.opt_strs("html-before-content"),
             &matches.opt_strs("html-after-content")) {
         Some(eh) => eh,
         None => return 3
@@ -291,17 +296,26 @@ pub fn main_args(args: &[String]) -> isize {
                 0
             }
             Some(s) => {
-                println!("unknown output format: {}", s);
+                print_error(format!("unknown output format: {}", s));
                 1
             }
         }
     });
     res.unwrap_or_else(|s| {
-        println!("input error: {}", s);
+        print_error(format!("input error: {}", s));
         1
     })
 }
 
+/// Prints an uniformised error message on the standard error output
+fn print_error<T>(error_message: T) where T: Display {
+    writeln!(
+        &mut io::stderr(),
+        "rustdoc: {}\nTry 'rustdoc --help' for more information.",
+        error_message
+    ).unwrap();
+}
+
 /// Looks inside the command line arguments to extract the relevant input format
 /// and files and then generates the necessary rustdoc output for formatting.
 fn acquire_input<R, F>(input: &str,

Diff for: src/librustdoc/markdown.rs

@@ -71,7 +71,7 @@ pub fn render(input: &str, mut output: PathBuf, matches: &getopts::Matches,
     let mut out = match File::create(&output) {
         Err(e) => {
             let _ = writeln!(&mut io::stderr(),
-                             "error opening `{}` for writing: {}",
+                             "rustdoc: {}: {}",
                              output.display(), e);
             return 4;
         }
@@ -80,8 +80,10 @@ pub fn render(input: &str, mut output: PathBuf, matches: &getopts::Matches,
 
     let (metadata, text) = extract_leading_metadata(&input_str);
     if metadata.is_empty() {
-        let _ = writeln!(&mut io::stderr(),
-                         "invalid markdown file: expecting initial line with `% ...TITLE...`");
+        let _ = writeln!(
+            &mut io::stderr(),
+            "rustdoc: invalid markdown file: expecting initial line with `% ...TITLE...`"
+        );
         return 5;
     }
     let title = metadata[0];
@@ -132,7 +134,7 @@ pub fn render(input: &str, mut output: PathBuf, matches: &getopts::Matches,
     match err {
         Err(e) => {
             let _ = writeln!(&mut io::stderr(),
-                             "error writing to `{}`: {}",
+                             "rustdoc: cannot write to `{}`: {}",
                              output.display(), e);
             6
         }