src/doc/rustdoc/src/passes.md

   1 # Passes
   2
   3 Rustdoc has a concept called "passes". These are transformations that
   4 `rustdoc` runs on your documentation before producing its final output.
   5
   6 In addition to the passes below, check out the docs for these flags:
   7
   8 * [`--passes`](command-line-arguments.html#a--passes-add-more-rustdoc-passes)
   9 * [`--no-defaults`](command-line-arguments.html#a--no-defaults-dont-run-default-passes)
  10
  11 ## Default passes
  12
  13 By default, rustdoc will run some passes, namely:
  14
  15 * `strip-hidden`
  16 * `strip-private`
  17 * `collapse-docs`
  18 * `unindent-comments`
  19
  20 However, `strip-private` implies `strip-private-imports`, and so effectively,
  21 all passes are run by default.
  22
  23 ## `strip-hidden`
  24
  25 This pass implements the `#[doc(hidden)]` attribute. When this pass runs, it
  26 checks each item, and if it is annotated with this attribute, it removes it
  27 from `rustdoc`'s output.
  28
  29 Without this pass, these items will remain in the output.
  30
  31 ## `unindent-comments`
  32
  33 When you write a doc comment like this:
  34
  35 ```rust,ignore
  36 /// This is a documentation comment.
  37 ```
  38
  39 There's a space between the `///` and that `T`. That spacing isn't intended
  40 to be a part of the output; it's there for humans, to help separate the doc
  41 comment syntax from the text of the comment. This pass is what removes that
  42 space.
  43
  44 The exact rules are left under-specified so that we can fix issues that we find.
  45
  46 Without this pass, the exact number of spaces is preserved.
  47
  48 ## `collapse-docs`
  49
  50 With this pass, multiple `#[doc]` attributes are converted into one single
  51 documentation string.
  52
  53 For example:
  54
  55 ```rust,ignore
  56 #[doc = "This is the first line."]
  57 #[doc = "This is the second line."]
  58 ```
  59
  60 Gets collapsed into a single doc string of
  61
  62 ```text
  63 This is the first line.
  64 This is the second line.
  65 ```
  66
  67 ## `strip-private`
  68
  69 This removes documentation for any non-public items, so for example:
  70
  71 ```rust,ignore
  72 /// These are private docs.
  73 struct Private;
  74
  75 /// These are public docs.
  76 pub struct Public;
  77 ```
  78
  79 This pass removes the docs for `Private`, since they're not public.
  80
  81 This pass implies `strip-priv-imports`.
  82
  83 ## `strip-priv-imports`
  84
  85 This is the same as `strip-private`, but for `extern crate` and `use`
  86 statements instead of items.