improve diagnostics for invalid external docs

Author: euclio

src/libsyntax/ext/expand.rs

@@ -1535,17 +1535,33 @@ impl<'a, 'b> Folder for InvocationCollector<'a, 'b> {
                             let item = attr::mk_list_item(DUMMY_SP, include_ident, include_info);
                             items.push(dummy_spanned(ast::NestedMetaItemKind::MetaItem(item)));
                         }
-                        Err(ref e) if e.kind() == ErrorKind::InvalidData => {
-                            self.cx.span_err(
-                                at.span,
-                                &format!("{} wasn't a utf-8 file", filename.display()),
-                            );
-                        }
                         Err(e) => {
-                            self.cx.span_err(
-                                at.span,
-                                &format!("couldn't read {}: {}", filename.display(), e),
-                            );
+                            let lit = it
+                                .meta_item()
+                                .and_then(|item| item.name_value_literal())
+                                .unwrap();
+
+                            if e.kind() == ErrorKind::InvalidData {
+                                self.cx
+                                    .struct_span_err(
+                                        lit.span,
+                                        &format!("{} wasn't a utf-8 file", filename.display()),
+                                    )
+                                    .span_label(lit.span, "contains invalid utf-8")
+                                    .emit();
+                            } else {
+                                let mut err = self.cx.struct_span_err(
+                                    lit.span,
+                                    &format!("couldn't read {}: {}", filename.display(), e),
+                                );
+                                err.span_label(lit.span, "couldn't read file");
+
+                                if e.kind() == ErrorKind::NotFound {
+                                    err.help("external doc paths are relative to the crate root");
+                                }
+
+                                err.emit();
+                            }
                         }
                     }
                 } else {

src/test/ui/extern/auxiliary/invalid-utf8.txt

@@ -0,0 +1 @@
+�(

src/test/ui/extern/external-doc-error.rs

@@ -2,8 +2,12 @@
 
 #![feature(external_doc)]
 
-#[doc(include = "not-a-file.md")] //~ ERROR: couldn't read
-pub struct SomeStruct;
+#[doc(include = "not-a-file.md")]
+pub struct SomeStruct; //~^ ERROR couldn't read
+                       //~| HELP external doc paths are relative to the crate root
+
+#[doc(include = "auxiliary/invalid-utf8.txt")]
+pub struct InvalidUtf8; //~^ ERROR wasn't a utf-8 file
 
 #[doc(include)]
 pub struct MissingPath; //~^ ERROR expected path

src/test/ui/extern/external-doc-error.stderr

@@ -1,32 +1,40 @@
 error: couldn't read $DIR/not-a-file.md: $FILE_NOT_FOUND_MSG (os error 2)
-  --> $DIR/external-doc-error.rs:5:1
+  --> $DIR/external-doc-error.rs:5:17
    |
-LL | #[doc(include = "not-a-file.md")] //~ ERROR: couldn't read
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+LL | #[doc(include = "not-a-file.md")]
+   |                 ^^^^^^^^^^^^^^^ couldn't read file
+   |
+   = help: external doc paths are relative to the crate root
+
+error: $DIR/auxiliary/invalid-utf8.txt wasn't a utf-8 file
+  --> $DIR/external-doc-error.rs:9:17
+   |
+LL | #[doc(include = "auxiliary/invalid-utf8.txt")]
+   |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ contains invalid utf-8
 
 error: expected path to external documentation
-  --> $DIR/external-doc-error.rs:8:7
+  --> $DIR/external-doc-error.rs:12:7
    |
 LL | #[doc(include)]
    |       ^^^^^^^ help: provide a file path with `=`: `include = "<path>"`
 
 error: expected path to external documentation
-  --> $DIR/external-doc-error.rs:13:7
+  --> $DIR/external-doc-error.rs:17:7
    |
 LL | #[doc(include("../README.md"))]
    |       ^^^^^^^^^^^^^^^^^^^^^^^ help: provide a file path with `=`: `include = "../README.md"`
 
 error: expected path to external documentation
-  --> $DIR/external-doc-error.rs:18:7
+  --> $DIR/external-doc-error.rs:22:7
    |
 LL | #[doc(include = 123)]
    |       ^^^^^^^^^^^^^ help: provide a file path with `=`: `include = "<path>"`
 
 error: expected path to external documentation
-  --> $DIR/external-doc-error.rs:23:7
+  --> $DIR/external-doc-error.rs:27:7
    |
 LL | #[doc(include(123))]
    |       ^^^^^^^^^^^^ help: provide a file path with `=`: `include = "<path>"`
 
-error: aborting due to 5 previous errors
+error: aborting due to 6 previous errors