remove stars at the beginning of multiline comments

[rust.git] / clippy_lints / src / doc.rs

diff --git a/clippy_lints/src/doc.rs b/clippy_lints/src/doc.rs
index 46c3bd5106811d7c0904d8522ca8c317ad2ebeef..6dbf2ea959e6a667f1be86e3a52079e48a3bf570 100644 (file)
--- a/clippy_lints/src/doc.rs
+++ b/clippy_lints/src/doc.rs
@@ -19,7 +19,8 @@
 ///
 /// **Examples:**
 /// ```rust
-/// /// Do something with the foo_bar parameter. See also that::other::module::foo.
+/// /// Do something with the foo_bar parameter. See also
+/// that::other::module::foo.
 /// // ^ `foo_bar` and `that::other::module::foo` should be ticked.
 /// fn doit(foo_bar) { .. }
 /// ```
@@ -78,7 +79,8 @@ fn next(&mut self) -> Option<Self::Item> {
 /// Cleanup documentation decoration (`///` and such).
 ///
 /// We can't use `syntax::attr::AttributeMethods::with_desugared_doc` or
-/// `syntax::parse::lexer::comments::strip_doc_comment_decoration` because we need to keep track of
+/// `syntax::parse::lexer::comments::strip_doc_comment_decoration` because we
+/// need to keep track of
 /// the spans but this function is inspired from the later.
 #[allow(cast_possible_truncation)]
 pub fn strip_doc_comment_decoration(comment: &str, span: Span) -> (String, Vec<(usize, Span)>) {
@@ -89,23 +91,57 @@ pub fn strip_doc_comment_decoration(comment: &str, span: Span) -> (String, Vec<(
             let doc = &comment[prefix.len()..];
             let mut doc = doc.to_owned();
             doc.push('\n');
-            return (doc.to_owned(), vec![(doc.len(), Span { lo: span.lo + BytePos(prefix.len() as u32), ..span })]);
+            return (
+                doc.to_owned(),
+                vec![
+                    (
+                        doc.len(),
+                        Span {
+                            lo: span.lo + BytePos(prefix.len() as u32),
+                            ..span
+                        }
+                    ),
+                ],
+            );
         }
     }
 
     if comment.starts_with("/*") {
         let doc = &comment[3..comment.len() - 2];
         let mut sizes = vec![];
-
+        let mut contains_initial_stars = false;
         for line in doc.lines() {
             let offset = line.as_ptr() as usize - comment.as_ptr() as usize;
             debug_assert_eq!(offset as u32 as usize, offset);
-
+            contains_initial_stars |= line.trim_left().starts_with('*');
             // +1 for the newline
-            sizes.push((line.len() + 1, Span { lo: span.lo + BytePos(offset as u32), ..span }));
+            sizes.push((
+                line.len() + 1,
+                Span {
+                    lo: span.lo + BytePos(offset as u32),
+                    ..span
+                },
+            ));
         }
-
-        return (doc.to_string(), sizes);
+        if !contains_initial_stars {
+            return (doc.to_string(), sizes);
+        }
+        // remove the initial '*'s if any
+        let mut no_stars = String::with_capacity(doc.len());
+        for line in doc.lines() {
+            let mut chars = line.chars();
+            while let Some(c) = chars.next() {
+                if c.is_whitespace() {
+                    no_stars.push(c);
+                } else {
+                    no_stars.push(if c == '*' { ' ' } else { c });
+                    break;
+                }
+            }
+            no_stars.push_str(chars.as_str());
+            no_stars.push('\n');
+        }
+        return (no_stars, sizes);
     }
 
     panic!("not a doc-comment: {}", comment);
@@ -163,7 +199,7 @@ fn check_doc<'a, Events: Iterator<Item = (usize, pulldown_cmark::Event<'a>)>>(
     cx: &EarlyContext,
     valid_idents: &[String],
     docs: Events,
-    spans: &[(usize, Span)]
+    spans: &[(usize, Span)],
 ) {
     use pulldown_cmark::Event::*;
     use pulldown_cmark::Tag::*;
@@ -192,7 +228,10 @@ fn check_doc<'a, Events: Iterator<Item = (usize, pulldown_cmark::Event<'a>)>>(
                     let (begin, span) = spans[index];
 
                     // Adjust for the begining of the current `Event`
-                    let span = Span { lo: span.lo + BytePos::from_usize(offset - begin), ..span };
+                    let span = Span {
+                        lo: span.lo + BytePos::from_usize(offset - begin),
+                        ..span
+                    };
 
                     check_text(cx, valid_idents, &text, span);
                 }
@@ -225,8 +264,10 @@ fn check_text(cx: &EarlyContext, valid_idents: &[String], text: &str, span: Span
 }
 
 fn check_word(cx: &EarlyContext, word: &str, span: Span) {
-    /// Checks if a string is camel-case, ie. contains at least two uppercase letter (`Clippy` is
-    /// ok) and one lower-case letter (`NASA` is ok). Plural are also excluded (`IDs` is ok).
+    /// Checks if a string is camel-case, ie. contains at least two uppercase
+    /// letter (`Clippy` is
+    /// ok) and one lower-case letter (`NASA` is ok). Plural are also excluded
+    /// (`IDs` is ok).
     fn is_camel_case(s: &str) -> bool {
         if s.starts_with(|c: char| c.is_digit(10)) {
             return false;
@@ -239,7 +280,7 @@ fn is_camel_case(s: &str) -> bool {
         };
 
         s.chars().all(char::is_alphanumeric) && s.chars().filter(|&c| c.is_uppercase()).take(2).count() > 1 &&
-        s.chars().filter(|&c| c.is_lowercase()).take(1).count() > 0
+            s.chars().filter(|&c| c.is_lowercase()).take(1).count() > 0
     }
 
     fn has_underscore(s: &str) -> bool {
@@ -247,9 +288,11 @@ fn has_underscore(s: &str) -> bool {
     }
 
     if has_underscore(word) || word.contains("::") || is_camel_case(word) {
-        span_lint(cx,
-                  DOC_MARKDOWN,
-                  span,
-                  &format!("you should put `{}` between ticks in the documentation", word));
+        span_lint(
+            cx,
+            DOC_MARKDOWN,
+            span,
+            &format!("you should put `{}` between ticks in the documentation", word),
+        );
     }
 }