From b2de57484835ee42567db3a1bf59f13ecc7fab33 Mon Sep 17 00:00:00 2001
From: Seiichi Uchida <seuchida@gmail.com>
Date: Thu, 11 Oct 2018 23:10:57 +0900
Subject: [PATCH] Add format_doc_comments

---
 Configurations.md                        | 50 ++++++++++++++++++++++++
 src/comment.rs                           |  9 +++--
 src/config/mod.rs                        |  1 +
 tests/source/doc-comment-with-example.rs |  2 +-
 tests/target/doc-comment-with-example.rs |  2 +-
 5 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/Configurations.md b/Configurations.md
index 66b5d840f3c36..f23506d5fe8d2 100644
--- a/Configurations.md
+++ b/Configurations.md
@@ -1979,6 +1979,56 @@ fn main() {
 }
 ```
 
+## `format_doc_comments`
+
+Format doc comments.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `false` (default):
+
+```rust
+/// Adds one to the number given.
+///
+/// # Examples
+///
+/// ```rust
+/// let five=5;
+///
+/// assert_eq!(
+///     6,
+///     add_one(5)
+/// );
+/// # fn add_one(x: i32) -> i32 {
+/// #     x + 1
+/// # }
+/// ```
+fn add_one(x: i32) -> i32 {
+    x + 1
+}
+```
+
+#### `true`
+
+```rust
+/// Adds one to the number given.
+///
+/// # Examples
+///
+/// ```rust
+/// let five = 5;
+///
+/// assert_eq!(6, add_one(5));
+/// # fn add_one(x: i32) -> i32 {
+/// #     x + 1
+/// # }
+/// ```
+fn add_one(x: i32) -> i32 {
+    x + 1
+}
+```
 
 ## `wrap_comments`
 
diff --git a/src/comment.rs b/src/comment.rs
index 4130152765313..213879e50a194 100644
--- a/src/comment.rs
+++ b/src/comment.rs
@@ -333,7 +333,10 @@ fn identify_comment(
     let rewritten_first_group =
         if !config.normalize_comments() && has_bare_lines && style.is_block_comment() {
             light_rewrite_block_comment_with_bare_lines(first_group, shape, config)?
-        } else if !config.normalize_comments() && !config.wrap_comments() {
+        } else if !config.normalize_comments()
+            && !config.wrap_comments()
+            && !config.format_doc_comments()
+        {
             light_rewrite_comment(first_group, shape.indent, config, is_doc_comment)?
         } else {
             rewrite_comment_inner(
@@ -593,7 +596,7 @@ fn rewrite_comment_inner(
                     _ if code_block_buffer.is_empty() => String::new(),
                     _ => {
                         let mut config = config.clone();
-                        config.set().wrap_comments(false);
+                        config.set().format_doc_comments(false);
                         match ::format_code_block(&code_block_buffer, &config) {
                             Some(ref s) => trim_custom_comment_prefix(s),
                             None => trim_custom_comment_prefix(&code_block_buffer),
@@ -1622,7 +1625,7 @@ mod test {
 
     #[test]
     #[rustfmt::skip]
-    fn format_comments() {
+    fn format_doc_comments() {
         let mut wrap_normalize_config: ::config::Config = Default::default();
         wrap_normalize_config.set().wrap_comments(true);
         wrap_normalize_config.set().normalize_comments(true);
diff --git a/src/config/mod.rs b/src/config/mod.rs
index a553bf2ee3c70..98754eb0b60a7 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -46,6 +46,7 @@ create_config! {
 
     // Comments. macros, and strings
     wrap_comments: bool, false, false, "Break comments to fit on the line";
+    format_doc_comments: bool, false, false, "Format doc comments.";
     comment_width: usize, 80, false,
         "Maximum length of comments. No effect unless wrap_comments = true";
     normalize_comments: bool, false, false, "Convert /* */ comments to // comments where possible";
diff --git a/tests/source/doc-comment-with-example.rs b/tests/source/doc-comment-with-example.rs
index 683ad789baf24..58d98acfa2556 100644
--- a/tests/source/doc-comment-with-example.rs
+++ b/tests/source/doc-comment-with-example.rs
@@ -1,4 +1,4 @@
-// rustfmt-wrap_comments: true
+// rustfmt-format_doc_comments: true
 
 /// Foo
 ///
diff --git a/tests/target/doc-comment-with-example.rs b/tests/target/doc-comment-with-example.rs
index bdf2adf0c6437..bec931d13c787 100644
--- a/tests/target/doc-comment-with-example.rs
+++ b/tests/target/doc-comment-with-example.rs
@@ -1,4 +1,4 @@
-// rustfmt-wrap_comments: true
+// rustfmt-format_doc_comments: true
 
 /// Foo
 ///