cargo doc: add option to document private types

[SimonSapin]

rustdoc can include private items in the generated documentation: rust-lang/rust#15347 (comment)
This is triggered by passing --no-defaults --passes "collapse-docs" --passes "unindent-comments" to it. This has two issues:

• It’s very hard to discover
• Cargo does not allow giving arbitrary parameters to rustdoc: cargo-doc: enable using --html-in-header and other rustdoc flags #331

Could Cargo do this itself e.g. when [lib] doc-private = true is set in Cargo.toml?

[dbrgn]

I'd prefer a cargo doc parameter instead of (or in addition to) the Cargo.toml version. Many times you want cargo doc to build the "official" documentation, but would like to use cargo doc --include-private to generate a version for yourself or other library devs.

[majkcramer]

+1

[LukasKalbertodt]

+1

Another idea: Would it make sense to enable doc generation of private types for non-library projects by default?

If you're developing a library, the docs are mainly for your users and those are not interested in private stuff. To not generate docs for private types by default makes sense here. Developers of the library can use the command line parameter to generate docs with private types for their use.

If you're developing a program (non-library), what are docs for then? Normal "users" of the program don't care about the source code and the documentation. So the docs are probably mainly for developers. It makes sense to generate docs for private types here. IMO.

[ssokolow]

@LukasKalbertodt

I have to agree. In my Python projects, I use ePyDoc to get a structured overview of my code when I'm returning from working on something else and the Rust book didn't even mention that private types wouldn't get documented.

Since my first project was an application project, that led me to get really frustrated because I thought it was something that was supposed to work and, thus, something I'd done wrong.

[dbrgn]

@LukasKalbertodt +1

[SimonSapin]

Cargo does not allow giving arbitrary parameters to rustdoc: #331

In Servo we’ve worked around that by calling Cargo with a RUSTDOC environment variable set to the name of this wrapper script:

#!/bin/sh
rustdoc --no-defaults --passes collapse-docs --passes unindent-comments "$@"

servo/servo#6655, servo/servo#6668

[ticki]

What is the state of this?

[jonas-schievink]

I think cargo rustdoc allows this and more, so the only thing left is to enable private docs for binaries by default, as per @LukasKalbertodt's suggestion (that's probably a different issue, though!). Oh, and this still is quite hard to discover.

[reem]

I also would like this for hosting internal documentation of libraries for people who want to develop those libraries vs. users of those libraries.

[dbrgn]

For the record, this seems to work:

$ cargo rustdoc -- --no-defaults --passes "collapse-docs" --passes "unindent-comments"

[solson]

Based on the newest servo rustdoc-with-private script and the cargo rustdoc command I tend to run cargo rustdoc --open -- --no-defaults --passes collapse-docs --passes unindent-comments --passes strip-priv-imports.

I think there should be first-class support for private docs during development, so I can do something like cargo doc --private --open or cargo doc --dev --open instead of writing a shell alias. Another aspect of this first-class support would be rustdoc showing which items are private and public, but that's outside the scope of this cargo issue.

EDIT: Well, rustdoc already shows pub in the page for an item, but not in links to that item or in lists of methods, so it could be a bit better.