Add a brief mention of doc comments (#509)

src/SUMMARY.md

@@ -32,6 +32,7 @@
   - [Slices](basic-syntax/slices.md)
     - [String vs str](basic-syntax/string-slices.md)
   - [Functions](basic-syntax/functions.md)
+    - [Rustdoc](basic-syntax/rustdoc.md)
     - [Methods](basic-syntax/methods.md)
     - [Overloading](basic-syntax/functions-interlude.md)
 - [Exercises](exercises/day-1/morning.md)

src/basic-syntax/rustdoc.md

@@ -0,0 +1,33 @@
+# Rustdoc
+
+All language items in Rust can be documented using special `///` syntax.
+
+```rust,editable
+/// Determine whether the first argument is divisible by the second argument.
+///
+/// If the second argument is zero, the result is false.
+fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
+    if rhs == 0 {
+        return false;  // Corner case, early return
+    }
+    lhs % rhs == 0     // The last expression in a block is the return value
+}
+```
+
+The contents are treated as Markdown. All published Rust library crates are
+automatically documented at [`docs.rs`](https://docs.rs) using the
+[rustdoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html) tool. It is
+idiomatic to document all public items in an API using this pattern.
+
+<details>
+
+* Show students the generated docs for the `rand` crate at
+  [`docs.rs/rand`](https://docs.rs/rand).
+
+* This course does not include rustdoc on slides, just to save space, but in
+  real code they should be present.
+
+* Inner doc comments are discussed later (in the page on modules) and need not
+  be addressed here.
+
+</details>

src/modules/filesystem.md

@@ -21,6 +21,20 @@ The `crate` root is in:
 * `src/lib.rs` (for a library crate)
 * `src/main.rs` (for a binary crate)
 
+Modules defined in files can be documented, too, using "inner doc comments".
+These document the item that contains them -- in this case, a module.
+
+```rust,editable,compile_fail
+//! This module implements the garden, including a highly performant germination
+//! implementation.
+
+/// Sow the given seed packets.
+fn sow(seeds: Vec<SeedPacket>) { todo!() }
+
+// Harvest the produce in the garden that is ready.
+fn harvest(garden: &mut Garden) { todo!() }
+```
+
 <details>
 
 * The change from `module/mod.rs` to `module.rs` doesn't preclude the use of submodules in Rust 2018.