New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cargo doc: add option to document private types #1520

Closed
SimonSapin opened this Issue Apr 13, 2015 · 26 comments

Comments

Projects
None yet
@SimonSapin
Contributor

SimonSapin commented Apr 13, 2015

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: #331

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

@dbrgn

This comment has been minimized.

Contributor

dbrgn commented May 20, 2015

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

This comment has been minimized.

majkcramer commented May 23, 2015

+1

@LukasKalbertodt

This comment has been minimized.

Contributor

LukasKalbertodt commented Aug 27, 2015

+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

This comment has been minimized.

ssokolow commented Aug 27, 2015

@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

This comment has been minimized.

Contributor

dbrgn commented Aug 27, 2015

@SimonSapin

This comment has been minimized.

Contributor

SimonSapin commented Aug 27, 2015

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

This comment has been minimized.

ticki commented Feb 6, 2016

What is the state of this?

@jonas-schievink

This comment has been minimized.

jonas-schievink commented Feb 6, 2016

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

This comment has been minimized.

reem commented Mar 4, 2016

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

This comment has been minimized.

Contributor

dbrgn commented Mar 10, 2016

For the record, this seems to work:

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

This comment has been minimized.

Member

solson commented Apr 8, 2016

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

This comment has been minimized.

Contributor

durka commented Aug 17, 2016

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. 👍 👍

Would a PR be accepted or is an RFC required?

@kelseasy

This comment has been minimized.

kelseasy commented Nov 30, 2016

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

This comment has been minimized.

NfNitLoop commented Mar 30, 2017

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

This comment has been minimized.

mbr commented Apr 12, 2017

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

@hdevalence

This comment has been minimized.

hdevalence commented Jun 27, 2017

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

This comment has been minimized.

pjmlp commented Jul 8, 2017

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

This comment has been minimized.

Zaerei commented Sep 20, 2017

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

This comment has been minimized.

Member

steveklabnik commented Sep 20, 2017

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

This comment has been minimized.

hobofan commented Jan 17, 2018

For anyone stumbling upon this, rust-lang/rust#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

This comment has been minimized.

glandium commented Mar 20, 2018

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.

@haxxpop

This comment has been minimized.

haxxpop commented Sep 6, 2018

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

@dwijnand

This comment has been minimized.

Member

dwijnand commented Sep 6, 2018

See #5958.

@ehuss

This comment has been minimized.

Contributor

ehuss commented Sep 6, 2018

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

@alexcrichton

This comment has been minimized.

Member

alexcrichton commented Sep 6, 2018

Indeed!

@LukasKalbertodt

This comment has been minimized.

Contributor

LukasKalbertodt commented Sep 12, 2018

@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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment