Throw errors when doc comments are added where they're unused

src/librustc/hir/mod.rs

@@ -892,6 +892,13 @@ impl Decl_ {
             DeclItem(_) => &[]
         }
     }
+
+    pub fn is_local(&self) -> bool {
+        match *self {
+            Decl_::DeclLocal(_) => true,
+            _ => false,
+        }
+    }
 }
 
 /// represents one arm of a 'match'
@@ -1679,7 +1686,7 @@ pub struct Item {
 
 #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
 pub enum Item_ {
-    /// An`extern crate` item, with optional original crate name,
+    /// An `extern crate` item, with optional original crate name,
     ///
     /// e.g. `extern crate foo` or `extern crate foo_bar as foo`
     ItemExternCrate(Option<Name>),

src/librustc/middle/region.rs

@@ -458,10 +458,10 @@ impl<'tcx> RegionMaps {
                                    -> CodeExtent {
         if scope_a == scope_b { return scope_a; }
 
-        /// [1] The initial values for `a_buf` and `b_buf` are not used.
-        /// The `ancestors_of` function will return some prefix that
-        /// is re-initialized with new values (or else fallback to a
-        /// heap-allocated vector).
+        // [1] The initial values for `a_buf` and `b_buf` are not used.
+        // The `ancestors_of` function will return some prefix that
+        // is re-initialized with new values (or else fallback to a
+        // heap-allocated vector).
         let mut a_buf: [CodeExtent; 32] = [scope_a /* [1] */; 32];
         let mut a_vec: Vec<CodeExtent> = vec![];
         let mut b_buf: [CodeExtent; 32] = [scope_b /* [1] */; 32];

src/librustc_lint/builtin.rs

@@ -722,6 +722,46 @@ impl EarlyLintPass for IllegalFloatLiteralPattern {
     }
 }
 
+declare_lint! {
+    pub UNUSED_DOC_COMMENT,
+    Warn,
+    "detects doc comments that aren't used by rustdoc"
+}
+
+#[derive(Copy, Clone)]
+pub struct UnusedDocComment;
+
+impl LintPass for UnusedDocComment {
+    fn get_lints(&self) -> LintArray {
+        lint_array![UNUSED_DOC_COMMENT]
+    }
+}
+
+impl UnusedDocComment {
+    fn warn_if_doc<'a, 'tcx,
+                   I: Iterator<Item=&'a ast::Attribute>,
+                   C: LintContext<'tcx>>(&self, mut attrs: I, cx: &C) {
+        if let Some(attr) = attrs.find(|a| a.is_value_str() && a.check_name("doc")) {
+            cx.struct_span_lint(UNUSED_DOC_COMMENT, attr.span, "doc comment not used by rustdoc")
+              .emit();
+        }
+    }
+}
+
+impl EarlyLintPass for UnusedDocComment {
+    fn check_local(&mut self, cx: &EarlyContext, decl: &ast::Local) {
+        self.warn_if_doc(decl.attrs.iter(), cx);
+    }
+
+    fn check_arm(&mut self, cx: &EarlyContext, arm: &ast::Arm) {
+        self.warn_if_doc(arm.attrs.iter(), cx);
+    }
+
+    fn check_expr(&mut self, cx: &EarlyContext, expr: &ast::Expr) {
+        self.warn_if_doc(expr.attrs.iter(), cx);
+    }
+}
+
 declare_lint! {
     pub UNCONDITIONAL_RECURSION,
     Warn,

src/librustc_lint/lib.rs

@@ -111,6 +111,7 @@ pub fn register_builtins(store: &mut lint::LintStore, sess: Option<&Session>) {
                        UnusedImportBraces,
                        AnonymousParameters,
                        IllegalFloatLiteralPattern,
+                       UnusedDocComment,
                        );
 
     add_early_builtin_with_new!(sess,

src/librustc_typeck/check/wfcheck.rs

@@ -89,23 +89,23 @@ impl<'a, 'gcx> CheckTypeWellFormedVisitor<'a, 'gcx> {
                tcx.item_path_str(tcx.hir.local_def_id(item.id)));
 
         match item.node {
-            /// Right now we check that every default trait implementation
-            /// has an implementation of itself. Basically, a case like:
-            ///
-            /// `impl Trait for T {}`
-            ///
-            /// has a requirement of `T: Trait` which was required for default
-            /// method implementations. Although this could be improved now that
-            /// there's a better infrastructure in place for this, it's being left
-            /// for a follow-up work.
-            ///
-            /// Since there's such a requirement, we need to check *just* positive
-            /// implementations, otherwise things like:
-            ///
-            /// impl !Send for T {}
-            ///
-            /// won't be allowed unless there's an *explicit* implementation of `Send`
-            /// for `T`
+            // Right now we check that every default trait implementation
+            // has an implementation of itself. Basically, a case like:
+            //
+            // `impl Trait for T {}`
+            //
+            // has a requirement of `T: Trait` which was required for default
+            // method implementations. Although this could be improved now that
+            // there's a better infrastructure in place for this, it's being left
+            // for a follow-up work.
+            //
+            // Since there's such a requirement, we need to check *just* positive
+            // implementations, otherwise things like:
+            //
+            // impl !Send for T {}
+            //
+            // won't be allowed unless there's an *explicit* implementation of `Send`
+            // for `T`
             hir::ItemImpl(_, hir::ImplPolarity::Positive, _, _,
                           ref trait_ref, ref self_ty, _) => {
                 self.check_impl(item, self_ty, trait_ref);

src/libsyntax/ast.rs

@@ -718,6 +718,13 @@ impl Stmt {
         };
         self
     }
+
+    pub fn is_item(&self) -> bool {
+        match self.node {
+            StmtKind::Local(_) => true,
+            _ => false,
+        }
+    }
 }
 
 impl fmt::Debug for Stmt {

src/libsyntax/parse/parser.rs

@@ -2131,14 +2131,14 @@ impl<'a> Parser<'a> {
                 } else {
                     Ok(self.mk_expr(span, ExprKind::Tup(es), attrs))
                 }
-            },
+            }
             token::OpenDelim(token::Brace) => {
                 return self.parse_block_expr(lo, BlockCheckMode::Default, attrs);
-            },
-            token::BinOp(token::Or) |  token::OrOr => {
+            }
+            token::BinOp(token::Or) | token::OrOr => {
                 let lo = self.span;
                 return self.parse_lambda_expr(lo, CaptureBy::Ref, attrs);
-            },
+            }
             token::OpenDelim(token::Bracket) => {
                 self.bump();
 
@@ -2387,7 +2387,6 @@ impl<'a> Parser<'a> {
     pub fn parse_block_expr(&mut self, lo: Span, blk_mode: BlockCheckMode,
                             outer_attrs: ThinVec<Attribute>)
                             -> PResult<'a, P<Expr>> {
-
         self.expect(&token::OpenDelim(token::Brace))?;
 
         let mut attrs = outer_attrs;

src/test/compile-fail/issue-34222.rs → src/test/compile-fail/useless_comment.rs

@@ -8,11 +8,23 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#![feature(rustc_attrs)]
-#![allow(warnings)]
+#![deny(unused_doc_comment)]
 
-#[rustc_error]
-fn main() { //~ ERROR compilation successful
-    /// crash
-    let x = 0;
+fn foo() {
+    /// a //~ ERROR doc comment not used by rustdoc
+    let x = 12;
+
+    /// b //~ doc comment not used by rustdoc
+    match x {
+        /// c //~ ERROR doc comment not used by rustdoc
+        1 => {},
+        _ => {}
+    }
+
+    /// foo //~ ERROR doc comment not used by rustdoc
+    unsafe {}
 }
+
+fn main() {
+    foo();
+}