Add explanation of main to rustdoc docs

Fixes #17554

diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md
index 054552559dbec077fb5a1fd4533b3f0d40b83efb..512d49196ef9ac1ace36c0081054596debafddb0 100644 (file)
--- a/src/doc/rustdoc.md
+++ b/src/doc/rustdoc.md
@@ -217,6 +217,35 @@ spawn(move || { fib(200); })
 The documentation online would look like `spawn(move || { fib(200); })`, but when
 testing this code, the `fib` function will be included (so it can compile).
 
+Rustdoc will automatically add a `main()` wrapper around your code, and in the right
+place. For example:
+
+```
+/// ```
+/// use std::rc::Rc;
+///
+/// let five = Rc::new(5);
+/// ```
+# fn foo() {}
+```
+
+This will end up testing:
+
+```
+fn main() {
+    use std::rc::Rc;
+    let five = Rc::new(5);
+}
+```
+
+Here's the full algorithm:
+
+1. Given a code block, if it does not contain `fn main`, it is wrapped in `fn main() { your_code }`
+2. Given that result, if it contains no `extern crate` directives but it also
+   contains the name of the crate being tested, then `extern crate <name>` is
+   injected at the top.
+3. Some common `allow` attributes are added for documentation examples at the top.
+
 ## Running tests (advanced)
 
 Running tests often requires some special configuration to filter tests, find