src/doc/rustdoc/src/what-is-rustdoc.md

   1 # What is rustdoc?
   2
   3 The standard Rust distribution ships with a tool called `rustdoc`. Its job is
   4 to generate documentation for Rust projects. On a fundamental level, Rustdoc
   5 takes as an argument either a crate root or a Markdown file, and produces HTML,
   6 CSS, and JavaScript.
   7
   8 ## Basic usage
   9
  10 Let's give it a try! Create a new project with Cargo:
  11
  12 ```bash
  13 $ cargo new docs --lib
  14 $ cd docs
  15 ```
  16
  17 In `src/lib.rs`, Cargo has generated some sample code. Delete
  18 it and replace it with this:
  19
  20 ```rust
  21 /// foo is a function
  22 fn foo() {}
  23 ```
  24
  25 Let's run `rustdoc` on our code. To do so, we can call it with the path to
  26 our crate root like this:
  27
  28 ```bash
  29 $ rustdoc src/lib.rs
  30 ```
  31
  32 This will create a new directory, `doc`, with a website inside! In our case,
  33 the main page is located in `doc/lib/index.html`. If you open that up in
  34 a web browser, you will see a page with a search bar, and "Crate lib" at the
  35 top, with no contents.
  36
  37 ## Configuring rustdoc
  38
  39 There are two problems with this: first, why does it
  40 think that our package is named "lib"? Second, why does it not have any
  41 contents?
  42
  43 The first problem is due to `rustdoc` trying to be helpful; like `rustc`,
  44 it assumes that our crate's name is the name of the file for the crate
  45 root. To fix this, we can pass in a command-line flag:
  46
  47 ```bash
  48 $ rustdoc src/lib.rs --crate-name docs
  49 ```
  50
  51 Now, `doc/docs/index.html` will be generated, and the page says "Crate docs."
  52
  53 For the second issue, it is because our function `foo` is not public; `rustdoc`
  54 defaults to generating documentation for only public functions. If we change
  55 our code...
  56
  57 ```rust
  58 /// foo is a function
  59 pub fn foo() {}
  60 ```
  61
  62 ... and then re-run `rustdoc`:
  63
  64 ```bash
  65 $ rustdoc src/lib.rs --crate-name docs
  66 ```
  67
  68 We now have some generated documentation. Open up `doc/docs/index.html` and
  69 check it out! It should show a link to the `foo` function's page, which
  70 is located at `doc/docs/fn.foo.html`. On that page, you'll see the "foo is
  71 a function" we put inside the documentation comment in our crate.
  72
  73 ## Using rustdoc with Cargo
  74
  75 Cargo also has integration with `rustdoc` to make it easier to generate
  76 docs. Instead of the `rustdoc` command, we could have done this:
  77
  78 ```bash
  79 $ cargo doc
  80 ```
  81
  82 Internally, this calls out to `rustdoc` like this:
  83
  84 ```bash
  85 $ rustdoc --crate-name docs src/lib.rs -o <path>/docs/target/doc -L
  86 dependency=<path>/docs/target/debug/deps
  87 ```
  88
  89 You can see this with `cargo doc --verbose`.
  90
  91 It generates the correct `--crate-name` for us, as well as pointing to
  92 `src/lib.rs`. But what about those other arguments?
  93  - `-o` controls the *o*utput of our docs. Instead of a top-level
  94  `doc` directory, notice that Cargo puts generated documentation under
  95  `target`. That is the idiomatic place for generated files in Cargo projects.
  96  - `-L` flag helps rustdoc find the dependencies your code relies on.
  97  If our project used dependencies, we would get documentation for them as well!
  98
  99 ## Outer and inner documentation
 100
 101 The `///` syntax is used to document the item present after it.
 102 That's why it is called an outer documentation.
 103 There is another syntax: `//!`, which is used to document the
 104 item it is present inside. It is called an inner documentation.
 105 It is often used when documenting the entire crate,
 106 because nothing comes before it: it is the root of the crate.
 107 So in order to document an entire crate, you need to use `//!` syntax.
 108 For example:
 109
 110 ``` rust
 111 //! This is my first rust crate
 112 ```
 113
 114 When used in the crate root, it documents the item it is inside,
 115 which is the crate itself.
 116
 117 For more information about the `//!` syntax, see [the Book].
 118
 119 [the Book]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commenting-contained-items
 120
 121
 122 ## Using standalone Markdown files
 123
 124 `rustdoc` can also generate HTML from standalone Markdown files. Let' s
 125 give it a try: create a `README.md` file with these contents:
 126
 127 ````text
 128 # Docs
 129
 130 This is a project to test out `rustdoc`.
 131
 132 [Here is a link!](https://www.rust-lang.org)
 133
 134 ## Example
 135
 136 ```rust
 137 fn foo() -> i32 {
 138     1 + 1
 139 }
 140 ```
 141 ````
 142
 143 And call `rustdoc` on it:
 144
 145 ```bash
 146 $ rustdoc README.md
 147 ```
 148
 149 You will find an HTML file in `docs/doc/README.html` generated from its
 150 Markdown contents.
 151
 152 Cargo currently does not understand standalone Markdown files, unfortunately.
 153
 154 ## Summary
 155
 156 This covers the simplest use-cases of `rustdoc`. The rest of this book will
 157 explain all of the options that `rustdoc` has, and how to use them.