parser: show a helpful note on unexpected inner comment

Fixes: #30318.

Author: birkenfeld

src/libsyntax/parse/attr.rs

@@ -35,7 +35,10 @@ impl<'a> Parser<'a> {
                     self.span.hi
                 );
                     if attr.node.style != ast::AttrStyle::Outer {
-                        return Err(self.fatal("expected outer comment"));
+                        let mut err = self.fatal("expected outer doc comment");
+                        err.note("inner doc comments like this (starting with \
+                                  `//!` or `/*!`) can only appear before items");
+                        return Err(err);
                     }
                     attrs.push(attr);
                     self.bump();

src/test/parse-fail/issue-30318.rs

@@ -0,0 +1,19 @@
+// Copyright 2016 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 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// compile-flags: -Z parse-only
+
+fn foo() { }
+
+//! Misplaced comment...
+//~^ ERROR expected outer doc comment
+//~| NOTE inner doc comments like this (starting with `//!` or `/*!`) can only appear before items
+
+fn main() { }