rustdoc: beyond documentation
FOSDEM 2020 - Rust devroom
Guillaume Gomez < guillaume1.gomez@gmail.com >
## Who am I?
Rust language reviewer and contributor.
Member of:
* rustdoc team (team leader)
* documentation team
* docs.rs team
* tools team
## Using rustdoc
```bash
$ cargo doc
$ cargo doc --open
```
### Fun fact
You can use **rustdoc** to convert markdown to HTML:
```bash
$ rustdoc your_markdown_file
```
## Documenting
```rust
//! Documenting current module.
/// Documenting the foo function.
pub fn foo(nb: i32) {}
```
### Syntactic sugar?
```rust
#![doc = "Documenting current module."]
#[doc = "Documenting the foo function."]
pub fn foo(nb: i32) {}
```
### Discover information on your own types!
* Blanket implementations
* Auto-traits
### Enforce documentation through lints
```rust
#![deny(missing_docs)]
#![deny(missing_doc_example)]
```
## Beyond documentation
What about *testing* the code examples?
````rust
/// Code example!
///
/// ```rust,no_run
/// let x = 12;
/// foo(x);
/// panic!("woups!");
/// ```
pub fn foo(nb: i32) {}
````
### Running doctests
```bash
$ cargo test
$ cargo test --doc
```
### More tags
* allow_fail
* compile_fail
* edition\[2015|2018|2021?\]
* ignore
* no_run
* rust
* should_panic
* everything else: instruction for syntax highlighting
## But's that not all!
* works with JS disabled
* search
* no need for internet connection
* source code viewer
* settings
* themes
* customizable
## What's coming next?
* more interactive soure code viewer
* automatic link generation based on the type name
* more output formats supported
* conditional documentation
* doc aliases for search