comments

`///` are doc comments.  however, they don't work for binaries, so we'll
have to wait a bit until `cargo doc` will generate something.

the book doesn't mention multiline comments, but they do exist.  (`/**`
are doc block comments.)

doc comments are also just a special syntax for `#[doc="..."]`
attributes.

rust/book/src/main.rs

@@ -1,3 +1,17 @@
/// `inc` is a function that increments it's argument, except if the
/// argument is 42.
///
/// # Arguments
///
/// * `x` - The number to increment
///
/// # Examples
///
/// ```rust
/// inc(3)  == 4
/// inc(42) == 42
/// inc(99) == 100
/// ```
fn inc(x: i32) -> i32 {
    if x == 42 {
        return 42
@@ -7,15 +21,16 @@ fn inc(x: i32) -> i32 {
}
fn main() {
    let x = 5;
    let x = 5; // x: i32
    println!("Hello, World!");
    if x == 42 {
    if x == 42 { // 42 is important
        println!("It's THE ANSWER!");
    } else {
        println!("Meh, it's just a number, {}.", x);
    }
    // let's call some functions
    let n = 10;
    println!("inc({}) = {}", n, inc(n));
    println!("inc(42) = {}", inc(42));