new restriction lint: doc_comment_double_space_linebreak

Author: Jacherr

CHANGELOG.md

@@ -5249,6 +5249,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

@@ -140,6 +140,7 @@ pub(crate) 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,52 @@
+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
+                && 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].to_owned());
+                Some((attr.span, new_comment))
+            } else {
+                None
+            }
+        })
+        .collect()
+}

clippy_lints/src/doc/mod.rs

@@ -28,6 +28,7 @@ use rustc_span::{sym, Span};
 use std::ops::Range;
 use url::Url;
 
+mod doc_comment_double_space_linebreak;
 mod link_with_quotes;
 mod markdown;
 mod missing_headers;
@@ -420,6 +421,39 @@ declare_clippy_lint! {
     "require every line of a paragraph to be indented and marked"
 }
 
+declare_clippy_lint! {
+    /// ### What it does
+    /// 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 `\\`"
+}
+
 #[derive(Clone)]
 pub struct Documentation {
     valid_idents: FxHashSet<String>,
@@ -447,6 +481,7 @@ impl_lint_pass!(Documentation => [
     SUSPICIOUS_DOC_COMMENTS,
     EMPTY_DOCS,
     DOC_LAZY_CONTINUATION,
+    DOC_COMMENT_DOUBLE_SPACE_LINEBREAK
 ]);
 
 impl<'tcx> LateLintPass<'tcx> for Documentation {
@@ -569,6 +604,7 @@ fn check_attrs(cx: &LateContext<'_>, valid_idents: &FxHashSet<String>, attrs: &[
     }
 
     suspicious_doc_comments::check(cx, attrs);
+    doc_comment_double_space_linebreak::check(cx, attrs);
 
     let (fragments, _) = attrs_to_doc_fragments(
         attrs.iter().filter_map(|attr| {

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
+