From 3390ff97b22e082bb553cc0f175ae5ca18bd5e60 Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume1.gomez@gmail.com>
Date: Wed, 22 Apr 2020 11:08:50 +0200
Subject: [PATCH 1/2] Add error code to inner doc comment attribute error

---
 src/librustc_error_codes/error_codes.rs       |  1 +
 src/librustc_error_codes/error_codes/E0753.md | 31 +++++++++++++++++++
 src/librustc_parse/parser/attr.rs             | 12 +++++--
 3 files changed, 41 insertions(+), 3 deletions(-)
 create mode 100644 src/librustc_error_codes/error_codes/E0753.md

diff --git a/src/librustc_error_codes/error_codes.rs b/src/librustc_error_codes/error_codes.rs
index bc04809eaa1df..9f4b5fd85fd4d 100644
--- a/src/librustc_error_codes/error_codes.rs
+++ b/src/librustc_error_codes/error_codes.rs
@@ -432,6 +432,7 @@ E0749: include_str!("./error_codes/E0749.md"),
 E0750: include_str!("./error_codes/E0750.md"),
 E0751: include_str!("./error_codes/E0751.md"),
 E0752: include_str!("./error_codes/E0752.md"),
+E0753: include_str!("./error_codes/E0753.md"),
 ;
 //  E0006, // merged with E0005
 //  E0008, // cannot bind by-move into a pattern guard
diff --git a/src/librustc_error_codes/error_codes/E0753.md b/src/librustc_error_codes/error_codes/E0753.md
new file mode 100644
index 0000000000000..a69da964aee39
--- /dev/null
+++ b/src/librustc_error_codes/error_codes/E0753.md
@@ -0,0 +1,31 @@
+An inner doc comment was used in an invalid context.
+
+Erroneous code example:
+
+```compile_fail,E0753
+fn foo() {}
+//! foo
+// ^ error!
+fn main() {}
+```
+
+Inner document can only be used before items. For example:
+
+```
+//! A working comment applied to the module!
+fn foo() {
+    //! Another working comment!
+}
+fn main() {}
+```
+
+In case you want to document the item following the doc comment, you might want
+to use outer doc comment:
+
+```
+/// I am an outer doc comment
+#[doc = "I am also an outer doc comment!"]
+fn foo() {
+    // ...
+}
+```
diff --git a/src/librustc_parse/parser/attr.rs b/src/librustc_parse/parser/attr.rs
index b56dd30739dae..803f14a2a228a 100644
--- a/src/librustc_parse/parser/attr.rs
+++ b/src/librustc_parse/parser/attr.rs
@@ -4,7 +4,7 @@ use rustc_ast::attr;
 use rustc_ast::token::{self, Nonterminal};
 use rustc_ast::util::comments;
 use rustc_ast_pretty::pprust;
-use rustc_errors::PResult;
+use rustc_errors::{error_code, PResult};
 use rustc_span::{Span, Symbol};
 
 use log::debug;
@@ -50,10 +50,16 @@ impl<'a> Parser<'a> {
             } else if let token::DocComment(s) = self.token.kind {
                 let attr = self.mk_doc_comment(s);
                 if attr.style != ast::AttrStyle::Outer {
-                    self.struct_span_err(self.token.span, "expected outer doc comment")
+                    self.sess
+                        .span_diagnostic
+                        .struct_span_err_with_code(
+                            self.token.span,
+                            "expected outer doc comment",
+                            error_code!(E0753),
+                        )
                         .note(
                             "inner doc comments like this (starting with \
-                              `//!` or `/*!`) can only appear before items",
+                             `//!` or `/*!`) can only appear before items",
                         )
                         .emit();
                 }

From 038f5b74336f310f495af0c15e4a2b4d0750cfee Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume1.gomez@gmail.com>
Date: Wed, 22 Apr 2020 11:09:57 +0200
Subject: [PATCH 2/2] Update UI tests

---
 src/test/ui/parser/doc-comment-in-if-statement.stderr | 3 ++-
 src/test/ui/parser/issue-30318.stderr                 | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/test/ui/parser/doc-comment-in-if-statement.stderr b/src/test/ui/parser/doc-comment-in-if-statement.stderr
index af21b78733f90..be52a0afd46b7 100644
--- a/src/test/ui/parser/doc-comment-in-if-statement.stderr
+++ b/src/test/ui/parser/doc-comment-in-if-statement.stderr
@@ -1,4 +1,4 @@
-error: expected outer doc comment
+error[E0753]: expected outer doc comment
   --> $DIR/doc-comment-in-if-statement.rs:2:13
    |
 LL |     if true /*!*/ {}
@@ -17,3 +17,4 @@ LL |     if true /*!*/ {}
 
 error: aborting due to 2 previous errors
 
+For more information about this error, try `rustc --explain E0753`.
diff --git a/src/test/ui/parser/issue-30318.stderr b/src/test/ui/parser/issue-30318.stderr
index 489451bb5dc8d..b3a27f1985171 100644
--- a/src/test/ui/parser/issue-30318.stderr
+++ b/src/test/ui/parser/issue-30318.stderr
@@ -1,4 +1,4 @@
-error: expected outer doc comment
+error[E0753]: expected outer doc comment
   --> $DIR/issue-30318.rs:3:1
    |
 LL | //! Misplaced comment...
@@ -8,3 +8,4 @@ LL | //! Misplaced comment...
 
 error: aborting due to previous error
 
+For more information about this error, try `rustc --explain E0753`.