src/doc/rust-by-example/src/meta/doc.md

   1 # Documentation
   2
   3 Use `cargo doc` to build documentation in `target/doc`, `cargo doc --open`
   4 will automatically open it in your web browser.
   5
   6 Use `cargo test` to run all tests (including documentation tests), and `cargo
   7 test --doc` to only run documentation tests.
   8
   9 These commands will appropriately invoke `rustdoc` (and `rustc`) as required.
  10
  11 ## Doc comments
  12
  13 Doc comments are very useful for big projects that require documentation. When
  14 running `rustdoc`, these are the comments that get compiled into
  15 documentation. They are denoted by a `///`, and support [Markdown].
  16
  17 ````rust,editable,ignore
  18 #![crate_name = "doc"]
  19
  20 /// A human being is represented here
  21 pub struct Person {
  22     /// A person must have a name, no matter how much Juliet may hate it
  23     name: String,
  24 }
  25
  26 impl Person {
  27     /// Creates a person with the given name.
  28     ///
  29     /// # Examples
  30     ///
  31     /// ```
  32     /// // You can have rust code between fences inside the comments
  33     /// // If you pass --test to `rustdoc`, it will even test it for you!
  34     /// use doc::Person;
  35     /// let person = Person::new("name");
  36     /// ```
  37     pub fn new(name: &str) -> Person {
  38         Person {
  39             name: name.to_string(),
  40         }
  41     }
  42
  43     /// Gives a friendly hello!
  44     ///
  45     /// Says "Hello, [name](Person::name)" to the `Person` it is called on.
  46     pub fn hello(&self) {
  47         println!("Hello, {}!", self.name);
  48     }
  49 }
  50
  51 fn main() {
  52     let john = Person::new("John");
  53
  54     john.hello();
  55 }
  56 ````
  57
  58 To run the tests, first build the code as a library, then tell `rustdoc` where
  59 to find the library so it can link it into each doctest program:
  60
  61 ```shell
  62 $ rustc doc.rs --crate-type lib
  63 $ rustdoc --test --extern doc="libdoc.rlib" doc.rs
  64 ```
  65
  66 ## Doc attributes
  67
  68 Below are a few examples of the most common `#[doc]` attributes used with
  69 `rustdoc`.
  70
  71 ### `inline`
  72
  73 Used to inline docs, instead of linking out to separate page.
  74
  75 ```rust,ignore
  76 #[doc(inline)]
  77 pub use bar::Bar;
  78
  79 /// bar docs
  80 pub mod bar {
  81     /// the docs for Bar
  82     pub struct Bar;
  83 }
  84 ```
  85
  86 ### `no_inline`
  87
  88 Used to prevent linking out to separate page or anywhere.
  89
  90 ```rust,ignore
  91 // Example from libcore/prelude
  92 #[doc(no_inline)]
  93 pub use crate::mem::drop;
  94 ```
  95
  96 ### `hidden`
  97
  98 Using this tells `rustdoc` not to include this in documentation:
  99
 100 ```rust,editable,ignore
 101 // Example from the futures-rs library
 102 #[doc(hidden)]
 103 pub use self::async_await::*;
 104 ```
 105
 106 For documentation, `rustdoc` is widely used by the community. It's what is used
 107 to generate the [std library docs](https://doc.rust-lang.org/std/).
 108
 109 ### See also:
 110
 111 - [The Rust Book: Making Useful Documentation Comments][book]
 112 - [The rustdoc Book][rustdoc-book]
 113 - [The Reference: Doc comments][ref-comments]
 114 - [RFC 1574: API Documentation Conventions][api-conv]
 115 - [RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)][intra-links]
 116 - [Is there any documentation style guide for comments? (reddit)][reddit]
 117
 118 [markdown]: https://en.wikipedia.org/wiki/Markdown
 119 [book]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
 120 [ref-comments]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments
 121 [rustdoc-book]: https://doc.rust-lang.org/rustdoc/index.html
 122 [api-conv]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text
 123 [intra-links]: https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html
 124 [reddit]: https://www.reddit.com/r/rust/comments/ahb50s/is_there_any_documentation_style_guide_for/