Try to solve issue 3417.

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Change option `format_doc_comment` to `format_code_in_doc_comment`.
 - `use_small_heuristics` changed to be an enum and stabilised. Configuration
   options are now ready for 1.0.
 

Configurations.md

@@ -1978,9 +1978,9 @@ fn main() {
 }
 ```
 
-## `format_doc_comments`
+## `format_code_in_doc_comments`
 
-Format doc comments.
+Format code snippet included in doc comments.
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`

src/comment.rs

@@ -353,7 +353,7 @@ fn identify_comment(
             trim_left_preserve_layout(first_group, shape.indent, config)?
         } else if !config.normalize_comments()
             && !config.wrap_comments()
-            && !config.format_doc_comments()
+            && !config.format_code_in_doc_comments()
         {
             light_rewrite_comment(first_group, shape.indent, config, is_doc_comment)
         } else {
@@ -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_code_in_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)
                         }
                     }
                 };

src/config/mod.rs

@@ -37,7 +37,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.";
+    format_code_in_doc_comments: bool, false, false, "Format the code snippet in 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";

tests/source/doc-comment-with-example.rs

@@ -1,4 +1,4 @@
-// rustfmt-format_doc_comments: true
+// rustfmt-format_code_in_doc_comments: true
 
 /// Foo
 ///

tests/source/invalid-rust-code-in-doc-comment.rs

@@ -1,4 +1,4 @@
-// rustfmt-format_doc_comments: true
+// rustfmt-format_code_in_doc_comments: true
 
 /// ```rust
 /// if (true) { … }

tests/source/issue-2520.rs

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

tests/source/issue-2523.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_code_in_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_code_in_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_code_in_doc_comments: true
 
 //! This is a list:
 //!  * Outer

tests/source/itemized-blocks/wrap.rs

@@ -1,4 +1,5 @@
 // rustfmt-wrap_comments: true
+// rustfmt-format_code_in_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/doc-comment-with-example.rs

@@ -1,4 +1,4 @@
-// rustfmt-format_doc_comments: true
+// rustfmt-format_code_in_doc_comments: true
 
 /// Foo
 ///

tests/target/invalid-rust-code-in-doc-comment.rs

@@ -1,4 +1,4 @@
-// rustfmt-format_doc_comments: true
+// rustfmt-format_code_in_doc_comments: true
 
 /// ```rust
 /// if (true) { … }

tests/target/issue-2520.rs

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

tests/target/issue-2523.rs

@@ -1,4 +1,5 @@
 // rustfmt-normalize_comments: true
+// rustfmt-format_code_in_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_code_in_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_code_in_doc_comments: true
 
 //! This is a list:
 //!  * Outer

tests/target/itemized-blocks/wrap.rs

@@ -1,4 +1,5 @@
 // rustfmt-wrap_comments: true
+// rustfmt-format_code_in_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() {}