Document that 'cargo test' will execute files in the examples/ directory

[Wilfred]

We don't seem to have any docs about Cargo's ability to run files in the examples/ directory.

I may have missed it, but I can't see it in chapter 11 of the new book. I also looked at testing and documentation in the old book but I didn't see it mentioned there either.

It would be nice to mention this groovy feature. I don't know exactly how it works, so perhaps mention what sort of examples we expect -- full programs or snippets, and whether they should print the output of the functions being shown, or whether to assert things about their output instead.

[carols10cents]

Thanks for the suggestion! I think this is better documented in Cargo's documentation, though. This is currently documented a bit in this section about examples and the following section on tests. Cargo docs can definitely be improved, and there are plans to make some improvements soon, especially since the Rust bookshelf RFC has been merged.

Also just fyi cargo test doesn't actually execute the files in the examples, it only compiles them. Have a great day! 🌆