Try to solve issue 3417.

Configurations.md

@@ -1980,7 +1980,7 @@ fn main() {
 
 ## `format_doc_comments`
 
-Format doc comments.
+Format code snippet in doc comments.
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`

src/comment.rs

@@ -656,9 +656,16 @@ impl<'a> CommentRewrite<'a> {
                     _ => {
                         let mut config = self.fmt.config.clone();
                         config.set().wrap_comments(false);
-                        match crate::format_code_block(&self.code_block_buffer, &config) {
-                            Some(ref s) => trim_custom_comment_prefix(&s.snippet),
-                            None => trim_custom_comment_prefix(&self.code_block_buffer),
+                        if config.format_doc_comments() {
+                            if let Some(s) =
+                                crate::format_code_block(&self.code_block_buffer, &config)
+                            {
+                                trim_custom_comment_prefix(&s.snippet)
+                            } else {
+                                trim_custom_comment_prefix(&self.code_block_buffer)
+                            }
+                        } else {
+                            trim_custom_comment_prefix(&self.code_block_buffer)
                         }
                     }
                 };

tests/source/issue-2520.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_doc_comments: true
 
 //! ```rust
 //! println!( "hello, world" );

tests/source/issue-2523.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_doc_comments: true
 
 // Do not unindent macro calls in comment with unformattable syntax.
 //! ```rust

tests/source/issue-3055/original.rs

@@ -1,4 +1,5 @@
 // rustfmt-wrap_comments: true
+// rustfmt-format_doc_comments: true
 
 /// Vestibulum elit nibh, rhoncus non, euismod sit amet, pretium eu, enim. Nunc commodo ultricies dui.
 ///

tests/source/itemized-blocks/no_wrap.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_doc_comments: true
 
 //! This is a list:
 //!  * Outer

tests/source/itemized-blocks/wrap.rs

@@ -1,4 +1,5 @@
 // rustfmt-wrap_comments: true
+// rustfmt-format_doc_comments: true
 // rustfmt-max_width: 50
 
 //! This is a list:

tests/source/normalize_doc_attributes_should_not_imply_format_doc_comments.rs

@@ -0,0 +1,15 @@
+// rustfmt-normalize_doc_attributes: true
+
+/// Foo
+///
+/// # Example
+/// ```
+/// # #![cfg_attr(not(dox), feature(cfg_target_feature, target_feature, stdsimd))]
+/// # #![cfg_attr(not(dox), no_std)]
+/// fn foo() {  }
+/// ```
+///
+fn foo() {}
+
+#[doc = "Bar documents"]
+fn bar() {}

tests/source/wrap_comments_should_not_imply_format_doc_comments.rs

@@ -0,0 +1,16 @@
+// rustfmt-wrap_comments: true
+
+/// Foo
+///
+/// # Example
+/// ```
+/// # #![cfg_attr(not(dox), feature(cfg_target_feature, target_feature, stdsimd))]
+/// # #![cfg_attr(not(dox), no_std)]
+/// fn foo() {  }
+/// ```
+///
+fn foo() {}
+
+/// A long commment for wrapping
+/// This is a long long long long long long long long long long long long long long long long long long long long sentence.
+fn bar() {}

tests/target/issue-2520.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_doc_comments: true
 
 //! ```rust
 //! println!("hello, world");

tests/target/issue-2523.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_doc_comments: true
 
 // Do not unindent macro calls in comment with unformattable syntax.
 //! ```rust

tests/target/issue-3055/original.rs

@@ -1,4 +1,5 @@
 // rustfmt-wrap_comments: true
+// rustfmt-format_doc_comments: true
 
 /// Vestibulum elit nibh, rhoncus non, euismod sit amet, pretium eu, enim. Nunc
 /// commodo ultricies dui.

tests/target/itemized-blocks/no_wrap.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_doc_comments: true
 
 //! This is a list:
 //!  * Outer

tests/target/itemized-blocks/wrap.rs

@@ -1,4 +1,5 @@
 // rustfmt-wrap_comments: true
+// rustfmt-format_doc_comments: true
 // rustfmt-max_width: 50
 
 //! This is a list:

tests/target/normalize_doc_attributes_should_not_imply_format_doc_comments.rs

@@ -0,0 +1,15 @@
+// rustfmt-normalize_doc_attributes: true
+
+/// Foo
+///
+/// # Example
+/// ```
+/// # #![cfg_attr(not(dox), feature(cfg_target_feature, target_feature, stdsimd))]
+/// # #![cfg_attr(not(dox), no_std)]
+/// fn foo() {  }
+/// ```
+///
+fn foo() {}
+
+///Bar documents
+fn bar() {}

tests/target/wrap_comments_should_not_imply_format_doc_comments.rs

@@ -0,0 +1,16 @@
+// rustfmt-wrap_comments: true
+
+/// Foo
+///
+/// # Example
+/// ```
+/// # #![cfg_attr(not(dox), feature(cfg_target_feature, target_feature, stdsimd))]
+/// # #![cfg_attr(not(dox), no_std)]
+/// fn foo() {  }
+/// ```
+fn foo() {}
+
+/// A long commment for wrapping
+/// This is a long long long long long long long long long long long long long
+/// long long long long long long long sentence.
+fn bar() {}