Release Profiles

$ cargo build 
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
$ cargo build --release
    Finished release [optimized] target(s) in 0.0s

Accurately documenting your packages will help other users know how and when to use them, so it's worth investing the time to wrtie documentation. In Chapter 3, we discussed how to comment Rust code using two slashes, //. Rust also has a particular kind of comment for documentation, The HTML displays the contents of documentation comments for public API items intended for programmers interested in knowing how to use your cate as opposed to how your crate is implemented.

Documentation comments use three slashes, ///, instead of two and support Markdown notation for formatting the text. Place documentation comments for an add_one function in a crate named my_crate.

Commonly Used Sections

We used the # Examples Markdown heading in Listing 14-1 to create a section in the HTML with the title "Examples". Here are some other sections that crate authors commonly use in their documentation:

• Panics: The scenarios in which the function being documented could panic. Callers of the function who don't want their programs to panic should make sure they don't call the function in these situations.

• Errors: If the function returns a Result, describing the kinds of errors that might occur and what conditions might cause those errors to be returned can be helpful to callers so they can write code to handle the different kinds of errors in different ways.

• Safety: If the function is unsafe to call (we discuss unsafety in Chapter 19), there should be a section explaining why the function is unsafe and covering the invariants that the function expects callers to uphold.

Most documentation comments don't need all of these sections, but this is a good checklist to remind you of the aspects of your code users will be interested in knowing about.

Documentation Comments as Tests

Adding example code blocks in your documentation comments can help demonstrate how to use your library, and doing so has an additional bonus: running cargo test will run the code examples in your documentation as tests! Nothing is better than documentation with examples, But nothing is worse than examples that don't work beccause the code has changed since the documentation was written. If we run cargo test with the documentation for the add_one function from Listing 14-1, we will see a section in the test results like this:

    Doc-tests package-manager
    
    running 1 test
    test src/lib.rs = add_one (line 5) ... ok
    
    test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 
        0 filtered out; finished in 0.9s

Now if we change either the function or the example so the assert_eq! in the example panics and run cargo test again, we'll see that the doc tests catch thata the example and the code are out of sync with each other!

Commenting Contained Items

The style of doc comment //! adds documentation to the item that contains the comments rather than to the items following the comments. These comments are useful for describing crates and modules especially. Use them to explain the overall purpose of the container to help your users understand the crate's organization.

Exporting a Convenient Public API with pub use

You can re-export items to make a public structure that's different from your private structure by using pub use. Re-exporting takes a public item in one location and makes it public in another location, as if it were defined in the other location instead.