Repository navigation
Wrapping code in fn main too much in the book's code examples #31249
Description
Activity
This may not be the "right" way, but…
rustdoc has a heuristic for guessing whether an example provides its own
fn main() { }. The heuristic is: "does the example contain the string"fn main". If rutsdoc thinks the example provides its ownfn main() { }, then it won't wrap the example in a main function. So maybe you can try writing a doc comment like this://! blah blah blah, example: //! //! ``` //! # // fn main //! #[test] //! fn blah() { //! assert!(false); //! } //! ```
I don't have a copy of rustbook handy to test this with, unfortunately.
Here's where that heuristic is documented: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests
And, if you don't know, starting a line in an example off with
#will hide that line when rustdoc renders the documentation.My email got lost in the GitHub outage :) Re-written below:
This is just normal Rustdoc behavior for examples. We can either:
Add a new rule about #[test]s
Fix it online by writing a main() explicitly.
The second is a lot less work, and isn't really worse. There's already a few situations where the default doesn't work and you have to do this; it's not clear to me more complex rules is helpful.
I've been saving the tab with half a response started in this textarea since the outage ;)
I researched what the new book is doing, and saw that it was using mdBook.
mdBook has the code-running feature implemented in a different way-- described in https://github.com/azerupi/mdBook/issues/29 (example. It also lets you hide lines with comments! So the new book might have a similar problem, but the code causing it is not the same.
So yeah, I guess this spot just needs a
# // fn main() {}:)- added a commit that references this issue
on Jan 29, 2016
I've only found this to be a problem in the testing section but there could be more.
In the code example that follows "Let's make our test fail:", if you click the "Run" button to open that example in the playground, running it exits successfully when it's supposed to fail because the test gets wrapped in
fn main:I'm not sure exactly where the
fn mainis being added, but if I inspect the HTML of the page there's a<span class="rusttest">that containsfn main:Is there a way to opt out of the main wrapping in this case?
I know @steveklabnik is redoing the book; is integration with play.rust-lang.org going to be a part of the new book too, or is this irrelevant? Is this something that's just part of TRPL or is it part of rustbook that other books might use?
I'm going to go research the answers to these questions but wanted to post this in the meantime :)