Format code block in doc comment

[crumblingstatue]

diff --git a/src/lib.rs b/src/lib.rs
index f07c890..5e5ab58 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,12 +1,14 @@
 //! Library for manipulating Game Maker Studio's "data.win" (GEN8) data files.
 //!
-//! Typical usage consists of reading [GameData](struct.GameData.html) from a file, doing stuff with it,
+//! Typical usage consists of reading [GameData](struct.GameData.html) from a
+//! file, doing stuff with it,
 //! then writing it back to a file.
 //!
 //! Example:
 //!
 //! ```no_run
-//! let mut game_data = rgmk::GameData::from_file("data.win").expect("Failed to open data.win");
+//! let mut game_data = rgmk::GameData::from_file("data.win").expect("Failed to
+//! open data.win");
 //! game_data.strings.strings[0] = "NYEH HEH HEH!".into();
 //! game_data.save_to_file("data.win").expect("Failed to save data.win");
 //! ```

Now the generated documentation looks like this:

[crumblingstatue]

I asked on IRC, it's probably not possible to have an escaped newline in doc comments.

Options include:

• Write an RFC for escaped newlines in doc comments

• Leave the strings alone inside code blocks in doc comments, even if they go above the column limit

• Try to be smart about reformatting the code inside code blocks inside doc comments.
  For example, this could be reformatted to

  //! let mut game_data = rgmk::GameData::from_file("data.win")
  //!                                    .expect("Failed to open data.win");
  

[nrc]

Option 3 seems to be the right solution here, but it is also a bit hard - it would mean re-parsing and so forth. Not impossible, but certainly a bit of work.

In the short term, we could just detect and skip code blocks in comments. Perhaps we should have more fine-grained options for skipping doc comments too?

[scanfield]

Given how frequent (in a good way) code-in-comments is, I do think we should do something special for it.

Am I right that we can depend on code blocks in comments looking like

a  bunch of code that should compile

And that we should use the algorithm from rustdoc:

1. Any leading #![foo] attributes are left intact as crate attributes.
2. Some common allow attributes are inserted, including unused_variables, unused_assignments, unused_mut, unused_attributes, and dead_code. Small examples often trigger these lints.
3. If the example does not contain extern crate, then extern crate <mycrate>; is inserted.
4. Finally, if the example does not contain fn main, the remainder of the text is wrapped in fn main() { your_code }

To produce code from examples that compiles. Then we'd format that, and then remove anything added by 1-4 to end up with the original code, formatted properly.

If any step fails, we leave the code as is and don't format the code within the block.

[topecongiro]

From 0.3.0 rustfmt leaves code blocks as is.