cargo doc: add option to document private types

[SimonSapin]

rustdoc can include private items in the generated documentation: https://github.com/rust-lang/rust/issues/15347#issuecomment-56939049
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: https://github.com/rust-lang/cargo/issues/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 "$@"

https://github.com/servo/servo/pull/6655, https://github.com/servo/servo/pull/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.

[durka]

How to do this is a fairly common question and though cargo rustdoc makes it tractable (I used to do this) the long incantation (even longer now with --passes strip-private-imports) is hardly welcoming to newcomers. I think this is an important option to add. :+1: :+1:

Would a PR be accepted or is an RFC required?

[kelseasy]

I would love to be able to do cargo doc --passes [...]. I'd be willing to work on this, through an RFC or a PR, whichever makes the most sense.

[NfNitLoop]

I just wanted this feature again today. Was showing off rustdoc for a binary crate I'm working on, but it's pretty unimpressive since none of its (sub)modules is public and I couldn't quickly remember the invocation to make cargo docs do what I wanted.

Add my name to the list of folks who would be happy to look into implementing this. :)

[mbr]

Please make this more accessible, I've been missing this feature countless times.

[hdevalence]

I'd also really like this feature. I also think it would be great to have a profile for "all docs", so that sites like docs.rs can build both "external" and "internal" docs -- this would mean that the internal docs are also linkable, which local doc builds aren't.

[pjmlp]

I would also join my voice to those complaining for lack of support.

Thanks to solson now I have a bash script calling into cargo, but it took me a while to find out how this is at all possible.

[Zaerei]

I feel like it would be nice to optionally have cargo doc generate both developer and public documentation. Something that would generate an index that by default goes to the public API with a header box that says

You are viewing the public API documentation, if you are working on this project you may want the
developer docs.

Where "developer docs" links to an alternate index.html compiled with --no-defaults --passes "collapse-docs" --passes "unindent-comments", and a similar header linking back to the public API.

Something simple and discoverable like cargo doc --include-dev-docs or something. You could probably do this without modifying too much by just outputting the docs in a doc/dev before the private type stripping pass and then again after the pass.

[steveklabnik]

A small note here, we plan on deprecating the --no-defaults --passes "collapse-docs" --passes "unindent-comments" shenanigans and introducing a more straightforward flag to generate private docs into Rustdoc.

[hobofan]

For anyone stumbling upon this, https://github.com/rust-lang/rust/pull/44138 has implemented the --document-private-items flag, which does the same as --no-defaults --passes "collapse-docs" --passes "unindent-comments".

cargo rustdoc -- --document-private-items

[glandium]

While cargo rustdoc -- --document-private-items is nice, it also doesn't work with virtual manifests (Cargo.toml with only a workspace defined), so a cargo doc option would be even nicer.

[ppopth]

Does anyone want --document-private-items in cargo doc? I do.

[dwijnand]

See #5958.

[ehuss]

This has been implemented in #5543 and is available in 1.29 beta. I think this can be closed.

[alexcrichton]

Indeed!

[LukasKalbertodt]

@alexcrichton What about the request to document private things by default for binary projects? I think quite a few people agree with that. And as far as I can see, the linked PR doesn't implement that. Should I create a separate issue for that?

[SOF3]

The docs are currently a bit confusing since it is not apparent from the index whether an item is private. In particular, if the private-module-public-reexport pattern is used, it would result in both items being displayed, making it really confusing even for myself. Is there an option to add a private icon (similar to the unsafe icon)?