cargo doc doesn't generate documentation for binary crate

[6D65]

Hi,

I'm not sure this is expected, though there's a mention in the rust book about cargo test for documentation working only with library crates. I don't see the reason why it wouldn't generate the documentation for a binary crate too.

Am I missing something?

[steveklabnik]

/cc @alexcrichton , who knows the reason. There is one, but I always forget

[alexcrichton]

This is actually just cargo test, a normal cargo doc does indeed generate documentation. Rustdoc inherently can't document a binary because it needs to link to a library to get the functions. This sort of thing would need to be fixed in rustdoc first unfortunately.

[BartMassey]

As far as I can tell cargo doc (as well as rustdoc proper) does not extract any documentation for functions in main.rs in a binary crate, although it does extract the container documentation for the crate itself. It would be really nice to be able to provide internal documentation for a program via rustdoc.

[BenSandeen]

@BartMassey I'm having the same problem; cargo doc is most definitely not generating documentation of the main.rs file in my binary crate, either.

[omarabid]

@alexcrichton documenting binaries could be useful for open source projects

[BartMassey]

@omarabid: This ancient incantation still works for documenting a binary crate, although it gives grim deprecation warnings:

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

This works without warnings, but included a useless top-level "Re-exports" section which clutters up the front page:

cargo rustdoc --open -- --document-private-items

I've added a comment to Rust Issue #44136 to this effect.

[bubolex]

--document-private-items is the best answer to this issue :)
Thank you @BartMassey