add empty_docs lint

Author: lucarlig

CHANGELOG.md

@@ -5158,6 +5158,7 @@ Released 2018-09-13
 [`duration_subsec`]: https://rust-lang.github.io/rust-clippy/master/index.html#duration_subsec
 [`eager_transmute`]: https://rust-lang.github.io/rust-clippy/master/index.html#eager_transmute
 [`else_if_without_else`]: https://rust-lang.github.io/rust-clippy/master/index.html#else_if_without_else
+[`empty_docs`]: https://rust-lang.github.io/rust-clippy/master/index.html#empty_docs
 [`empty_drop`]: https://rust-lang.github.io/rust-clippy/master/index.html#empty_drop
 [`empty_enum`]: https://rust-lang.github.io/rust-clippy/master/index.html#empty_enum
 [`empty_enum_variants_with_brackets`]: https://rust-lang.github.io/rust-clippy/master/index.html#empty_enum_variants_with_brackets

clippy_lints/src/declared_lints.rs

@@ -152,6 +152,7 @@ pub(crate) static LINTS: &[&crate::LintInfo] = &[
     crate::drop_forget_ref::MEM_FORGET_INFO,
     crate::duplicate_mod::DUPLICATE_MOD_INFO,
     crate::else_if_without_else::ELSE_IF_WITHOUT_ELSE_INFO,
+    crate::empty_docs::EMPTY_DOCS_INFO,
     crate::empty_drop::EMPTY_DROP_INFO,
     crate::empty_enum::EMPTY_ENUM_INFO,
     crate::empty_with_brackets::EMPTY_ENUM_VARIANTS_WITH_BRACKETS_INFO,

clippy_lints/src/empty_docs.rs

@@ -0,0 +1,58 @@
+use clippy_utils::diagnostics::span_lint_and_help;
+use rustc_ast::ast::*;
+use rustc_lint::{EarlyContext, EarlyLintPass};
+use rustc_session::declare_lint_pass;
+
+declare_clippy_lint! {
+    /// ### What it does
+    /// Detects documentation that is empty.
+    /// ### Why is this bad?
+    /// It is unlikely that there is any reason to have empty documentation for an item
+    ///
+    /// ### Example
+    /// ```rust
+    /// ///
+    /// fn returns_true() -> bool {
+    ///     true
+    /// }
+    /// ```
+    /// Use instead:
+    /// ```rust
+    /// fn returns_true() -> bool {
+    ///     true
+    /// }
+    /// ```
+    #[clippy::version = "1.74.0"]
+    pub EMPTY_DOCS,
+    suspicious,
+    "docstrings exist but documentation is empty"
+}
+
+declare_lint_pass!(EmptyDocs => [EMPTY_DOCS]);
+
+fn trim_comment(comment: &str) -> String {
+    comment
+        .trim()
+        .split("\n")
+        .map(|comment| comment.trim().trim_matches('*').trim_matches('!'))
+        .filter(|line| !line.is_empty())
+        .collect::<Vec<&str>>()
+        .join("")
+}
+
+impl EarlyLintPass for EmptyDocs {
+    fn check_attribute(&mut self, cx: &EarlyContext<'_>, attribute: &Attribute) {
+        if let AttrKind::DocComment(_line, comment) = attribute.kind {
+            if trim_comment(comment.as_str()).len() == 0 {
+                span_lint_and_help(
+                    cx,
+                    EMPTY_DOCS,
+                    attribute.span,
+                    "empty doc comment",
+                    None,
+                    "consider removing or fill it",
+                );
+            }
+        }
+    }
+}

clippy_lints/src/lib.rs

@@ -119,6 +119,7 @@ mod double_parens;
 mod drop_forget_ref;
 mod duplicate_mod;
 mod else_if_without_else;
+mod empty_docs;
 mod empty_drop;
 mod empty_enum;
 mod empty_with_brackets;
@@ -1116,6 +1117,7 @@ pub fn register_lints(store: &mut rustc_lint::LintStore, conf: &'static Conf) {
     });
     store.register_late_pass(move |_| Box::new(incompatible_msrv::IncompatibleMsrv::new(msrv())));
     store.register_late_pass(|_| Box::new(to_string_trait_impl::ToStringTraitImpl));
+    store.register_early_pass(|| Box::new(empty_docs::EmptyDocs));
     // add lints here, do not remove this comment, it's used in `new_lint`
 }
 

tests/ui/empty_docs.rs

@@ -0,0 +1,26 @@
+#![allow(unused)]
+#![warn(clippy::empty_docs)]
+
+pub mod outer_module {
+
+    //!
+    //! valid doc comment
+    //!!
+    //!! valid doc comment
+
+    ///
+    /// valid doc comment
+    ///
+    /// valid block doc comment
+
+    /**
+     *
+     */
+
+    /**
+     * valid block doc comment
+     *
+     */
+
+    pub mod inner_module {}
+}

tests/ui/empty_docs.stderr

@@ -0,0 +1,46 @@
+error: empty doc comment
+  --> tests/ui/empty_docs.rs:11:5
+   |
+LL |     ///
+   |     ^^^
+   |
+   = help: consider removing or fill it
+   = note: `-D clippy::empty-docs` implied by `-D warnings`
+   = help: to override `-D warnings` add `#[allow(clippy::empty_docs)]`
+
+error: empty doc comment
+  --> tests/ui/empty_docs.rs:13:5
+   |
+LL |     ///
+   |     ^^^
+   |
+   = help: consider removing or fill it
+
+error: empty doc comment
+  --> tests/ui/empty_docs.rs:16:5
+   |
+LL | /     /**
+LL | |      *
+LL | |      */
+   | |_______^
+   |
+   = help: consider removing or fill it
+
+error: empty doc comment
+  --> tests/ui/empty_docs.rs:6:5
+   |
+LL |     //!
+   |     ^^^
+   |
+   = help: consider removing or fill it
+
+error: empty doc comment
+  --> tests/ui/empty_docs.rs:8:5
+   |
+LL |     //!!
+   |     ^^^^
+   |
+   = help: consider removing or fill it
+
+error: aborting due to 5 previous errors
+