new restriction lint: doc_comment_double_space_linebreak

Author: Jacherr

CHANGELOG.md

@@ -5441,6 +5441,7 @@ Released 2018-09-13
 [`disallowed_type`]: https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_type
 [`disallowed_types`]: https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_types
 [`diverging_sub_expression`]: https://rust-lang.github.io/rust-clippy/master/index.html#diverging_sub_expression
+[`doc_comment_double_space_linebreak`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_comment_double_space_linebreak
 [`doc_lazy_continuation`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
 [`doc_link_with_quotes`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_link_with_quotes
 [`doc_markdown`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

clippy_lints/src/declared_lints.rs

@@ -135,6 +135,7 @@ pub static LINTS: &[&crate::LintInfo] = &[
     crate::disallowed_names::DISALLOWED_NAMES_INFO,
     crate::disallowed_script_idents::DISALLOWED_SCRIPT_IDENTS_INFO,
     crate::disallowed_types::DISALLOWED_TYPES_INFO,
+    crate::doc::DOC_COMMENT_DOUBLE_SPACE_LINEBREAK_INFO,
     crate::doc::DOC_LAZY_CONTINUATION_INFO,
     crate::doc::DOC_LINK_WITH_QUOTES_INFO,
     crate::doc::DOC_MARKDOWN_INFO,

clippy_lints/src/doc/doc_comment_double_space_linebreak.rs

@@ -0,0 +1,100 @@
+use std::borrow::Cow;
+
+use clippy_utils::diagnostics::span_lint_and_then;
+use clippy_utils::source::snippet;
+use pulldown_cmark::CowStr;
+use rustc_errors::Applicability;
+use rustc_lint::LateContext;
+use rustc_span::Span;
+
+use super::DOC_COMMENT_DOUBLE_SPACE_LINEBREAK;
+
+pub fn check(cx: &LateContext<'_>, collected_breaks: Vec<(Span, (Span, CowStr<'_>), Cow<'_, str>)>) {
+    let replacements: Vec<_> = collect_doc_replacements(cx, &collected_breaks);
+
+    if let Some((&(lo_span, _), &(hi_span, _))) = replacements.first().zip(replacements.last()) {
+        span_lint_and_then(
+            cx,
+            DOC_COMMENT_DOUBLE_SPACE_LINEBREAK,
+            lo_span.to(hi_span),
+            "doc comments should use a back-slash (\\) instead of a double space to indicate a linebreak",
+            |diag| {
+                diag.multipart_suggestion(
+                    "replace this double space with a back-slash",
+                    replacements,
+                    Applicability::MachineApplicable,
+                );
+            },
+        );
+    }
+}
+
+fn collect_doc_replacements(
+    cx: &LateContext<'_>,
+    attrs: &[(Span, (Span, CowStr<'_>), Cow<'_, str>)],
+) -> Vec<(Span, String)> {
+    attrs
+        .iter()
+        .map(|attr| {
+            let full = attr.0;
+            let new_comment = format!("\\\n/// ");
+            (full, new_comment)
+        })
+        .collect()
+}
+
+/*
+use clippy_utils::diagnostics::span_lint_and_then;
+use rustc_ast::token::CommentKind;
+use rustc_ast::{AttrKind, AttrStyle, Attribute};
+use rustc_errors::Applicability;
+use rustc_lint::LateContext;
+use rustc_span::Span;
+
+use super::DOC_COMMENT_DOUBLE_SPACE_LINEBREAK;
+
+pub fn check(cx: &LateContext<'_>, attrs: &[Attribute]) {
+    let replacements: Vec<_> = collect_doc_replacements(attrs);
+
+    if let Some((&(lo_span, _), &(hi_span, _))) = replacements.first().zip(replacements.last()) {
+        span_lint_and_then(
+            cx,
+            DOC_COMMENT_DOUBLE_SPACE_LINEBREAK,
+            lo_span.to(hi_span),
+            "doc comments should use a back-slash (\\) instead of a double space to indicate a linebreak",
+            |diag| {
+                diag.multipart_suggestion(
+                    "replace this double space with a back-slash",
+                    replacements,
+                    Applicability::MachineApplicable,
+                );
+            },
+        );
+    }
+}
+
+fn collect_doc_replacements(attrs: &[Attribute]) -> Vec<(Span, String)> {
+    attrs
+        .iter()
+        .filter_map(|attr| {
+            if let AttrKind::DocComment(com_kind, sym) = attr.kind
+                && !attr.span.from_expansion()
+                && com_kind == CommentKind::Line
+                && let comment = sym.as_str()
+                && comment.ends_with("  ")
+            {
+                let pre = match attr.style {
+                    AttrStyle::Outer => "///",
+                    AttrStyle::Inner => "//!",
+                };
+
+                let len = comment.len();
+                let new_comment = format!("{pre}{}\\", &comment[..len - 2]);
+                Some((attr.span, new_comment))
+            } else {
+                None
+            }
+        })
+        .collect()
+}
+*/

clippy_lints/src/doc/mod.rs

@@ -5,6 +5,7 @@ use clippy_config::Conf;
 use clippy_utils::attrs::is_doc_hidden;
 use clippy_utils::diagnostics::{span_lint, span_lint_and_help};
 use clippy_utils::macros::{is_panic, root_macro_call_first_node};
+use clippy_utils::source::snippet;
 use clippy_utils::ty::is_type_diagnostic_item;
 use clippy_utils::visitors::Visitable;
 use clippy_utils::{is_entrypoint_fn, is_trait_impl_item, method_chain_args};
@@ -28,11 +29,13 @@ use rustc_resolve::rustdoc::{
 };
 use rustc_session::impl_lint_pass;
 use rustc_span::edition::Edition;
-use rustc_span::{Span, sym};
+use rustc_span::{sym, Span};
+use std::borrow::Cow;
 use std::ops::Range;
 use url::Url;
 
 mod empty_line_after;
+mod doc_comment_double_space_linebreak;
 mod link_with_quotes;
 mod markdown;
 mod missing_headers;
@@ -532,6 +535,38 @@ declare_clippy_lint! {
     "empty line after doc comments"
 }
 
+declare_clippy_lint! {
+    /// Detects doc comment linebreaks that use double spaces to separate lines, instead of back-slash (\).
+    ///
+    /// ### Why is this bad?
+    /// Double spaces, when used as doc comment linebreaks, can be difficult to see, and may
+    /// accidentally be removed during automatic fofmatting or manual refactoring. The use of a back-slash (\)
+    /// is clearer in this regard.
+    ///
+    /// ### Example
+    /// The two dots in this example represent a double space.
+    /// ```no_run
+    /// /// This command takes two numbers as inputs and..
+    /// /// adds them together, and then returns the result.
+    /// fn add(l: i32, r: i32) -> i32 {
+    ///     l + r
+    /// }
+    /// ``````
+    ///
+    /// Use instead:
+    /// ```no_run
+    /// /// This command takes two numbers as inputs and \
+    /// /// adds them together, and then returns the result.
+    /// fn add(l: i32, r: i32) -> i32 {
+    ///     l + r
+    /// }
+    /// ```
+    #[clippy::version = "1.80.0"]
+    pub DOC_COMMENT_DOUBLE_SPACE_LINEBREAK,
+    restriction,
+    "double-space used for doc comment linebreak instead of `\\`"
+}
+
 pub struct Documentation {
     valid_idents: FxHashSet<String>,
     check_private_items: bool,
@@ -561,6 +596,7 @@ impl_lint_pass!(Documentation => [
     EMPTY_LINE_AFTER_OUTER_ATTR,
     EMPTY_LINE_AFTER_DOC_COMMENTS,
     TOO_LONG_FIRST_DOC_PARAGRAPH,
+    DOC_COMMENT_DOUBLE_SPACE_LINEBREAK
 ]);
 
 impl<'tcx> LateLintPass<'tcx> for Documentation {
@@ -694,6 +730,8 @@ fn check_attrs(cx: &LateContext<'_>, valid_idents: &FxHashSet<String>, attrs: &[
         return None;
     }
 
+    suspicious_doc_comments::check(cx, attrs);
+
     let (fragments, _) = attrs_to_doc_fragments(
         attrs.iter().filter_map(|attr| {
             if in_external_macro(cx.sess(), attr.span) {
@@ -776,8 +814,7 @@ fn check_doc<'a, Events: Iterator<Item = (pulldown_cmark::Event<'a>, Range<usize
     let mut paragraph_range = 0..0;
     let mut code_level = 0;
     let mut blockquote_level = 0;
-    let mut is_first_paragraph = true;
-
+    let mut collected_breaks: Vec<(Span, (Span, CowStr<'_>), Cow<'_, str>)> = Vec::new();
     let mut containers = Vec::new();
 
     let mut events = events.peekable();
@@ -894,8 +931,20 @@ fn check_doc<'a, Events: Iterator<Item = (pulldown_cmark::Event<'a>, Range<usize
                         &containers[..],
                     );
                 }
+
+                if let Some(span) = fragments.span(cx, range.clone()) 
+                    && let Some(ref p) = prev_text
+                    && let snippet = snippet(cx, span, "..") 
+                    && !snippet.trim().starts_with("\\")
+                    && event == HardBreak {
+                    collected_breaks.push((span, p.clone(), snippet));
+                    prev_text = None;
+                }
             },
             Text(text) => {
+                if let Some(span) = fragments.span(cx, range.clone()) {
+                    prev_text = Some((span, text.clone()));
+                }
                 paragraph_range.end = range.end;
                 let range_ = range.clone();
                 ticks_unbalanced |= text.contains('`')
@@ -943,6 +992,9 @@ fn check_doc<'a, Events: Iterator<Item = (pulldown_cmark::Event<'a>, Range<usize
             FootnoteReference(_) => {}
         }
     }
+
+    doc_comment_double_space_linebreak::check(cx, collected_breaks);
+
     headers
 }
 

tests/ui/doc/doc_comment_double_space_linebreak.fixed

@@ -0,0 +1,43 @@
+#![feature(custom_inner_attributes)]
+#![rustfmt::skip]
+
+#![warn(clippy::doc_comment_double_space_linebreak)]
+#![allow(unused)]
+
+//! Should warn on double space linebreaks \
+//! in file/module doc comment
+
+/// Should not warn on single-line doc comments
+fn single_line() {}
+
+/// Should not warn on single-line doc comments
+/// split across multiple lines
+fn single_line_split() {}
+
+// Should not warn on normal comments
+
+// note: cargo fmt can remove double spaces from normal and block comments
+// Should not warn on normal comments  
+// with double spaces at the end of a line
+
+fn normal_comment() {
+    /*
+       Should not warn on block comments
+    */
+
+    /*
+        Should not warn on block comments  
+        with double space at the end of a line
+     */
+}
+
+/// Should warn when doc comment uses double space \
+/// as a line-break, even when there are multiple \
+/// in a row
+fn double_space_doc_comment() {}
+
+/// Should not warn when back-slash is used \
+/// as a line-break
+fn back_slash_doc_comment() {}
+
+fn main() {}

tests/ui/doc/doc_comment_double_space_linebreak.rs

@@ -0,0 +1,43 @@
+#![feature(custom_inner_attributes)]
+#![rustfmt::skip]
+
+#![warn(clippy::doc_comment_double_space_linebreak)]
+#![allow(unused)]
+
+//! Should warn on double space linebreaks  
+//! in file/module doc comment
+
+/// Should not warn on single-line doc comments
+fn single_line() {}
+
+/// Should not warn on single-line doc comments
+/// split across multiple lines
+fn single_line_split() {}
+
+// Should not warn on normal comments
+
+// note: cargo fmt can remove double spaces from normal and block comments
+// Should not warn on normal comments  
+// with double spaces at the end of a line
+
+fn normal_comment() {
+    /*
+       Should not warn on block comments
+    */
+
+    /*
+        Should not warn on block comments  
+        with double space at the end of a line
+     */
+}
+
+/// Should warn when doc comment uses double space  
+/// as a line-break, even when there are multiple  
+/// in a row
+fn double_space_doc_comment() {}
+
+/// Should not warn when back-slash is used \
+/// as a line-break
+fn back_slash_doc_comment() {}
+
+fn main() {}

tests/ui/doc/doc_comment_double_space_linebreak.stderr

@@ -0,0 +1,24 @@
+error: doc comments should use a back-slash (\) instead of a double space to indicate a linebreak
+  --> tests/ui/doc/doc_comment_double_space_linebreak.rs:7:1
+   |
+LL | //! Should warn on double space linebreaks  
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: replace this double space with a back-slash: `//! Should warn on double space linebreaks \`
+   |
+   = note: `-D clippy::doc-comment-double-space-linebreak` implied by `-D warnings`
+   = help: to override `-D warnings` add `#[allow(clippy::doc_comment_double_space_linebreak)]`
+
+error: doc comments should use a back-slash (\) instead of a double space to indicate a linebreak
+  --> tests/ui/doc/doc_comment_double_space_linebreak.rs:34:1
+   |
+LL | / /// Should warn when doc comment uses double space  
+LL | | /// as a line-break, even when there are multiple  
+   | |___________________________________________________^
+   |
+help: replace this double space with a back-slash
+   |
+LL + /// Should warn when doc comment uses double space \
+LL + /// as a line-break, even when there are multiple \
+   |
+
+error: aborting due to 2 previous errors
+