Add new comment_within_doc lint

Author: GuillaumeGomez

CHANGELOG.md

@@ -5779,6 +5779,7 @@ Released 2018-09-13
 [`collapsible_match`]: https://rust-lang.github.io/rust-clippy/master/index.html#collapsible_match
 [`collapsible_str_replace`]: https://rust-lang.github.io/rust-clippy/master/index.html#collapsible_str_replace
 [`collection_is_never_read`]: https://rust-lang.github.io/rust-clippy/master/index.html#collection_is_never_read
+[`comment_within_doc`]: https://rust-lang.github.io/rust-clippy/master/index.html#comment_within_doc
 [`comparison_chain`]: https://rust-lang.github.io/rust-clippy/master/index.html#comparison_chain
 [`comparison_to_empty`]: https://rust-lang.github.io/rust-clippy/master/index.html#comparison_to_empty
 [`confusing_method_to_numeric_cast`]: https://rust-lang.github.io/rust-clippy/master/index.html#confusing_method_to_numeric_cast

clippy_lints/src/declared_lints.rs

@@ -112,6 +112,7 @@ pub static LINTS: &[&::declare_clippy_lint::LintInfo] = &[
     crate::disallowed_names::DISALLOWED_NAMES_INFO,
     crate::disallowed_script_idents::DISALLOWED_SCRIPT_IDENTS_INFO,
     crate::disallowed_types::DISALLOWED_TYPES_INFO,
+    crate::doc::COMMENT_WITHIN_DOC_INFO,
     crate::doc::DOC_BROKEN_LINK_INFO,
     crate::doc::DOC_COMMENT_DOUBLE_SPACE_LINEBREAKS_INFO,
     crate::doc::DOC_INCLUDE_WITHOUT_CFG_INFO,

clippy_lints/src/doc/comment_within_doc.rs

@@ -0,0 +1,109 @@
+use rustc_ast::token::CommentKind;
+use rustc_ast::{AttrKind, AttrStyle};
+use rustc_errors::Applicability;
+use rustc_lexer::{TokenKind, tokenize};
+use rustc_lint::{EarlyContext, LintContext};
+use rustc_span::source_map::SourceMap;
+use rustc_span::{BytePos, Span};
+
+use clippy_utils::diagnostics::span_lint_and_then;
+
+use super::COMMENT_WITHIN_DOC;
+
+struct AttrInfo {
+    line: usize,
+    is_outer: bool,
+    span: Span,
+    file_span_pos: BytePos,
+}
+
+impl AttrInfo {
+    fn new(source_map: &SourceMap, attr: &rustc_ast::Attribute) -> Option<Self> {
+        let span_info = source_map.span_to_lines(attr.span).ok()?;
+        // If we cannot get the line for any reason, no point in building this item.
+        let line = span_info.lines.last()?.line_index;
+        Some(Self {
+            line,
+            is_outer: attr.style == AttrStyle::Outer,
+            span: attr.span,
+            file_span_pos: span_info.file.start_pos,
+        })
+    }
+}
+
+// Returns a `Vec` of `TokenKind` if the span only contains comments, otherwise returns `None`.
+fn snippet_contains_only_comments(snippet: &str) -> Option<Vec<TokenKind>> {
+    let mut tokens = Vec::new();
+    for token in tokenize(snippet) {
+        match token.kind {
+            TokenKind::Whitespace => {},
+            TokenKind::BlockComment { .. } | TokenKind::LineComment { .. } => tokens.push(token.kind),
+            _ => return None,
+        }
+    }
+    Some(tokens)
+}
+
+pub(super) fn check(cx: &EarlyContext<'_>, attrs: &[rustc_ast::Attribute]) {
+    let mut stored_prev_attr = None;
+    let source_map = cx.sess().source_map();
+    for attr in attrs
+        .iter()
+        // We ignore `#[doc = "..."]` and `/** */` attributes.
+        .filter(|attr| matches!(attr.kind, AttrKind::DocComment(CommentKind::Line, _)))
+    {
+        let Some(attr) = AttrInfo::new(source_map, attr) else {
+            stored_prev_attr = None;
+            continue;
+        };
+        let Some(prev_attr) = stored_prev_attr else {
+            stored_prev_attr = Some(attr);
+            continue;
+        };
+        // First we check if they are from the same file and if they are the same kind of doc
+        // comments.
+        if attr.file_span_pos != prev_attr.file_span_pos || attr.is_outer != prev_attr.is_outer {
+            stored_prev_attr = Some(attr);
+            continue;
+        }
+        let Some(nb_lines) = attr.line.checked_sub(prev_attr.line + 1) else {
+            continue;
+        };
+        // Then we check if they follow each other.
+        if nb_lines == 0 || nb_lines > 1 {
+            // If there is no line between them or there are more than 1, we skip this check.
+            stored_prev_attr = Some(attr);
+            continue;
+        }
+        let span_between = prev_attr.span.between(attr.span);
+        // If there is one line between the two doc comments and this line contains a line code
+        // comment, then we lint.
+        if nb_lines == 1
+            && let Ok(snippet) = source_map.span_to_snippet(span_between)
+            && let Some(comments) = snippet_contains_only_comments(&snippet)
+            && let &[TokenKind::LineComment { .. }] = comments.as_slice()
+        {
+            let offset_begin = snippet.len() - snippet.trim_start().len();
+            let offset_end = snippet.len() - snippet.trim_end().len();
+            let span = span_between
+                .with_lo(span_between.lo() + BytePos(offset_begin.try_into().unwrap()))
+                .with_hi(span_between.hi() - BytePos(offset_end.try_into().unwrap()));
+            let comment_kind = if attr.is_outer { '/' } else { '!' };
+            span_lint_and_then(
+                cx,
+                COMMENT_WITHIN_DOC,
+                vec![prev_attr.span, span, attr.span],
+                "code comment surrounded by doc comments",
+                |diag| {
+                    diag.span_suggestion(
+                        span.with_hi(span.lo() + BytePos(2)),
+                        "did you mean to make it a doc comment?",
+                        format!("//{comment_kind}"),
+                        Applicability::MaybeIncorrect,
+                    );
+                },
+            );
+        }
+        stored_prev_attr = Some(attr);
+    }
+}

clippy_lints/src/doc/mod.rs

@@ -25,6 +25,7 @@ use std::ops::Range;
 use url::Url;
 
 mod broken_link;
+mod comment_within_doc;
 mod doc_comment_double_space_linebreaks;
 mod doc_suspicious_footnotes;
 mod include_in_doc_without_cfg;
@@ -668,6 +669,31 @@ declare_clippy_lint! {
     "looks like a link or footnote ref, but with no definition"
 }
 
+declare_clippy_lint! {
+    /// ### What it does
+    /// Checks if a code comment is surrounded by doc comments.
+    ///
+    /// ### Why is this bad?
+    /// This is likely a typo, making the documentation miss a line.
+    ///
+    /// ### Example
+    /// ```no_run
+    /// //! Doc
+    /// // oups
+    /// //! doc
+    /// ```
+    /// Use instead:
+    /// ```no_run
+    /// //! Doc
+    /// //! oups
+    /// //! doc
+    /// ```
+    #[clippy::version = "1.90.0"]
+    pub COMMENT_WITHIN_DOC,
+    pedantic,
+    "code comment surrounded by doc comments"
+}
+
 pub struct Documentation {
     valid_idents: FxHashSet<String>,
     check_private_items: bool,
@@ -702,11 +728,13 @@ impl_lint_pass!(Documentation => [
     DOC_INCLUDE_WITHOUT_CFG,
     DOC_COMMENT_DOUBLE_SPACE_LINEBREAKS,
     DOC_SUSPICIOUS_FOOTNOTES,
+    COMMENT_WITHIN_DOC,
 ]);
 
 impl EarlyLintPass for Documentation {
     fn check_attributes(&mut self, cx: &EarlyContext<'_>, attrs: &[rustc_ast::Attribute]) {
         include_in_doc_without_cfg::check(cx, attrs);
+        comment_within_doc::check(cx, attrs);
     }
 }