stop auto-wrapping code snippets in fn main()

[mikemorris]

I'm guessing this would be a semver breaking change, but would be happy to do the accompanying work of migrating code snippets in https://github.com/rust-lang/book to include fn main() {} wrapping explicitly (and #![allow(unused_variables)] where necessary) if this change is accepted (and the book migration could actually happen first because of the current text.contains("fn main") exclusion).

This seems to be a somewhat persistent issue in code snippet formatting in the Rust book, particularly for src/lib.rs files, with some awkward fixes (see expanded Listing 11-12 in https://doc.rust-lang.org/stable/book/ch11-03-test-organization.html for implications of this approach, extraneous code still added) without a particularly good solution (using the ignore class seems undesirable).

An alternative implementation could be adding support for a class like nomain or nowrap instead of changing this default behavior.

Refs #222 for initial implementation, #283 (quick_main! macro), #618, #712, rust-lang/book#1206, rust-lang/book#1874 (editable prevents fn main() wrapping), rust-lang/book#1982

Examples of problematic code snippets in the Rust book:

• https://doc.rust-lang.org/stable/book/ch11-03-test-organization.html
• https://doc.rust-lang.org/stable/book/ch15-05-interior-mutability.html#a-use-case-for-interior-mutability-mock-objects
• https://doc.rust-lang.org/stable/book/ch17-02-trait-objects.html
• https://doc.rust-lang.org/stable/book/ch17-03-oo-design-patterns.html#defining-post-and-creating-a-new-instance-in-the-draft-state

[carols10cents]

Note that this is only changing the rendering for the playground snippet presented in the HTML. Rustdoc also does auto main wrapping, and mdbook test uses rustdoc's testing, so the awkward fixes in the book that allow them to be not ignored like in rust-lang/book#1339 would still need to happen unless rustdoc gains the ability to specify in another way that the code shouldn't be wrapped in main.

[Dylan-DPC-zz]

The next release is most likely going to be a breaking change so that shouldn't matter

[mikemorris]

@carols10cents Thanks for mentioning the wrapping in rustdoc, wasn't aware of that - I took a look into rustdoc and it looks like there's some pretty well-tested functionality around dont_insert_main and already_has_main in https://github.com/rust-lang/rust/blob/master/src/librustdoc/test.rs.

Should rustdoc add "contents contain #[cfg(test)] or #[test]" as an exclusion case for wrapping (is this technically allowed alongside a main function or not?) and/or would adding a rustdoc attribute for skipping the wrapping behavior be a possibility?

Does rustdoc actually run test blocks like in the code snippet in rust-lang/book#1339?

[carols10cents]

You'd have to ask the rustdoc team those questions; I'd recommend opening an issue on rust-lang/rust and tagging rust-lang/rustdoc.

[ehuss]

Yea, I don't think this can be done in this way. Whatever the solution is will need to start with rustdoc. Some options:

• rustdoc could be smarter about what it wraps in main (seems very hard).
• tell rustdoc that a code block is a "test" and it should build and run it with the harness (seems tricky).
• add an annotation that something should compile (as a lib?), but not be run/tested.

There are probably better ideas out there.

Another question is if you expect the #[test] functions to actually run. Currently they are only checked that they compile.

[ehuss]

I think the solution for this will likely need to start with rustdoc. When rustdoc has better main wrapping smarts, we can revisit updating mdbook.