normalize_doc_attributes option: convert doc attributes to comments

Convert `#![doc]` and `#[doc]` attributes to `//!` and `///` doc comments.

Configurations.md

@@ -2188,6 +2188,32 @@ If you want to format code that requires edition 2018, add the following to your
 edition = "2018"
 ```
 
+## `normalize_doc_attributes`
+
+Convert `#![doc]` and `#[doc]` attributes to `//!` and `///` doc comments.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `false` (default):
+
+```rust
+#![doc = "Example documentation"]
+
+#[doc = "Example item documentation"]
+pub enum Foo {}
+```
+
+#### `true`:
+
+```rust
+//! Example documentation
+
+/// Example item documentation
+pub enum Foo {}
+```
+
 ## `emit_mode`
 
 Internal option

src/attr.rs

@@ -10,7 +10,7 @@
 
 //! Format attributes and meta items.
 
-use comment::{contains_comment, rewrite_doc_comment};
+use comment::{contains_comment, rewrite_doc_comment, CommentStyle};
 use config::lists::*;
 use config::IndentStyle;
 use expr::rewrite_literal;
@@ -350,11 +350,34 @@ impl Rewrite for ast::Attribute {
             if contains_comment(snippet) {
                 return Some(snippet.to_owned());
             }
+
+            let meta = self.meta();
+
+            // This attribute is possibly a doc attribute needing normalization to a doc comment
+            if context.config.normalize_doc_attributes() {
+                if let Some(ref meta) = meta {
+                    if meta.check_name("doc") {
+                        if let Some(ref literal) = meta.value_str() {
+                            let comment_style = match self.style {
+                                ast::AttrStyle::Inner => CommentStyle::Doc,
+                                ast::AttrStyle::Outer => CommentStyle::TripleSlash,
+                            };
+
+                            let doc_comment = format!("{}{}", comment_style.opener(), literal);
+                            return rewrite_doc_comment(
+                                &doc_comment,
+                                shape.comment(context.config),
+                                context.config,
+                            );
+                        }
+                    }
+                }
+            }
+
             // 1 = `[`
             let shape = shape.offset_left(prefix.len() + 1)?;
             Some(
-                self.meta()
-                    .and_then(|meta| meta.rewrite(context, shape))
+                meta.and_then(|meta| meta.rewrite(context, shape))
                     .map_or_else(|| snippet.to_owned(), |rw| format!("{}[{}]", prefix, rw)),
             )
         }

src/config/mod.rs

@@ -107,6 +107,7 @@ create_config! {
     blank_lines_lower_bound: usize, 0, false,
         "Minimum number of blank lines which must be put between items";
     edition: Edition, Edition::Edition2015, false, "The edition of the parser (RFC 2052)";
+    normalize_doc_attributes: bool, false, false, "Normalize doc attributes as doc comments";
 
     // Options that can change the source code beyond whitespace/blocks (somewhat linty things)
     merge_derives: bool, true, true, "Merge multiple `#[derive(...)]` into a single one";

tests/source/doc-attrib.rs

@@ -0,0 +1,11 @@
+// rustfmt-wrap_comments: true
+// rustfmt-normalize_doc_attributes: true
+
+#![doc = "Example doc attribute comment"]
+
+// Long `#[doc = "..."]`
+struct A { #[doc = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"] b: i32 }
+
+
+#[doc = "The `nodes` and `edges` method each return instantiations of `Cow<[T]>` to leave implementers the freedom to create entirely new vectors or to pass back slices into internally owned vectors."]
+struct B { b: i32 }

tests/target/doc-attrib.rs

@@ -0,0 +1,17 @@
+// rustfmt-wrap_comments: true
+// rustfmt-normalize_doc_attributes: true
+
+//! Example doc attribute comment
+
+// Long `#[doc = "..."]`
+struct A {
+    /// xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+    b: i32,
+}
+
+/// The `nodes` and `edges` method each return instantiations of `Cow<[T]>` to
+/// leave implementers the freedom to create entirely new vectors or to pass
+/// back slices into internally owned vectors.
+struct B {
+    b: i32,
+}