22

I'm currently working on a project with Rust and Cargo. It works well, but I encounter a little issue: for code reuse, most of my project is inside a lib crate. In this crate, a lot of things is private. So when I do cargo doc, I just have documentation for public, exported stuff... which is actually great, because it's easy to see what is exported and what is not.

But I have to admit: I miss a complete documentation of the whole project, for development purpose...

Shepmaster
  • 388,571
  • 95
  • 1,107
  • 1,366
lthms
  • 509
  • 3
  • 10
  • 4
    The [currently accepted answer](https://stackoverflow.com/a/39374515/155423) is not the best solution now. Consider accepting a different answer with a more up-to-date solution. – Shepmaster Feb 26 '20 at 13:38

4 Answers4

25

Rust 1.41

Documentation for binaries includes private items from the binary crate by default.

Rust 1.29

You can now use cargo doc --document-private-items

Previous versions

You may not be able to do it with Cargo today, there is a workaround if you use rustdoc directly.

Run cargo doc -v and make a note of the rustdoc command it runs:

$ cargo doc -v
   Compiling docz v0.0.1 (file:///private/tmp/docz)
     Running `rustdoc src/lib.rs -o /private/tmp/docz/target/doc --crate-name docz -L dependency=/private/tmp/docz/target/debug -L dependency=/private/tmp/docz/target/debug/deps`

Then, add --no-defaults --passes strip-hidden --passes collapse-docs --passes unindent-comments to the command:

rustdoc src/lib.rs -o /private/tmp/docz/target/doc --crate-name docz \
    -L dependency=/private/tmp/docz/target/debug \
    -L dependency=/private/tmp/docz/target/debug/deps \
    --no-defaults \
    --passes strip-hidden --passes collapse-docs --passes unindent-comments
Shepmaster
  • 388,571
  • 95
  • 1,107
  • 1,366
13

Use cargo to document private items:

cargo doc --document-private-items
joelparkerhenderson
  • 34,808
  • 19
  • 98
  • 119
  • 6
    You can also add a `.cargo/config` file to you project if you want it to be default: `[build] rustdocflags = ["--document-private-items"]` – Thomas Giesel Jan 01 '20 at 16:20
8

This can be done by passing arguments to rustdoc, after --, eg.

cargo rustdoc -- \
    --no-defaults \
    --passes strip-hidden \
    --passes collapse-docs \
    --passes unindent-comments \
    --passes strip-priv-imports

Based on @Shepmaster's answer, no need for manual copy-pasting.

ideasman42
  • 42,413
  • 44
  • 197
  • 320
  • `warning: the 'no-defaults' flag is considered deprecated`. Same for `passes`. The warnings recommend `--document-private-items` – lucidbrot Sep 15 '19 at 20:04
8

This is now simpler, just use:

cargo rustdoc -- --document-private-items
Zitrax
  • 19,036
  • 20
  • 88
  • 110
  • 4
    `rustdoc` requires running against an actual package, so it won't work with [a virtual manifest](https://doc.rust-lang.org/cargo/reference/manifest.html#the-workspace-section). It's better to use `cargo doc --document-private-items`, which works with virtual manifests too. – Alexander Batischev Feb 25 '19 at 18:52