Add option to include private definition in the documentation.

[nwin]

Please add an option for rustdoc such that rustdoc creates a proper documentation for private definitions.

While it is in general a good idea to hide these private definitions, as a crate developer it would be very valuable to have a good internal documentation of private types and functions.

[steveklabnik]

I'm -1. You can use regular comments for internal documentation.

[alexcrichton]

Closing, you can actually do this today!

rustdoc --no-defaults --passes collapse-docs --passes unindent-comments

By default rustdoc has a pass to strip private items, but those flags are just disabling that pass from running. rustdoc -h should give you more information.

[nwin]

This at least not work in my crate. All private definitions are still hidden.

Beside that, I get a strange error message "ERROR:rustdoc: unknown pass collapse-docs unindent-comments, skipping" when I use both passes.

[alexcrichton]

Hm it appears that they seem to no longer work! reopening.

[SimonSapin]

I’d like this (and a way to have cargo doc enable it) for http://doc.servo.org. rustdoc is useful not only when using a library, but also when working on that library itself. Granted, the two use cases are separate so this shouldn't be on by default.

I'm -1. You can use regular comments for internal documentation.

Navigation in a text editor is not nearly as easy as in rustdoc, where clicking on most things gets you to the documentation of that thing. This is invaluable when working on a large code base that you don’t know very well.

[drewcrawford]

+1. Writing a library, would benefit from being able to see private documentation while I work.

[drewcrawford]

It does look like the workaround

--no-defaults --passes "collapse-docs" --passes "unindent-comments"

works. (Need multiple invocations for "passes").

Recommend close.

[SimonSapin]

@drewcrawford are these rustdoc arguments? Can cargo doc be made to use them?

[drewcrawford]

They're rustdoc arguments. cargo doc can't be taught them, but I'd encourage you to comment in rust-lang/cargo#331 on that topic.

[SimonSapin]

We turned this on on http://doc.servo.org/ . It’s better, but not ideal: all use and extern crate statements show up as well. It’s pretty noisy. #27104

[SimonSapin]

@alexcrichton, could you edit #15347 (comment) ?

--passes "collapse-docs unindent-comments" causes ERROR:rustdoc: unknown pass collapse-docs unindent-comments, skipping which I ignored at first since docs still seem to be generated, but all doc-comments are truncated to their first line for a reason I don’t understand. servo/servo#6668 I’m unsure if this should be filed as a rustdoc bug. It does give an error message, after all.

It should be --passes collapse-docs --passes unindent-comments, with only one value per --passes.

[gnzlbg]

Would it be possible to always generate a "Developer documentation" section for crates that contains the docs of private items alongside the documentation for the public API ? Both should obviously be separated, but I think it is valuable to have both, and for users to always be able to read both.

[KalitaAlexey]

I agree with gnzlbg. Sometimes it is good to be able to search.

[Razican]

It's something that does not change how official documentation is handled, but that could help a bunch of us.

[gnzlbg]

I don't see why it shouldn't be provided for the official documentation as well, the split between public API and developer documentation would jut need to be made very clear. Say somebody properly documented some internal standard library function, and I want to read its documentation because I think doing so is FUN.

Do I really need to read it online in the source file? Or do I need to get a copy and generate it my self?

Seems like unnecessary hassle and probably is contraproductive.

Having easier ways to get people to know the internals of libraries, including the standard library is_good_. It helps people become contributors, it gets more eyes on the libraries internals and their implementation, it finds bugs if someone goes "wait a second, that doesn't make sense", or improves performance if somebody else goes "why are they using this algorithm, this other one is way better!".

[wraithan]

Since this had more search priority than a lot of the other issues around this topic, putting a note here that in rust-lang/cargo#5543 an option cargo doc --document-private-items was added. Sorry if this is an unwelcome comment, just wanted others who search for "cargo doc private" to be able to find the solution.

[AlbertMarashi]

+1

As both a user and maintainer of library it would be valauable to have a full "developer" section.

I'd argue that many users would benefit from also understanding internals directly from docs, even if they are not going to directly use them.

[jyn514]

Please do not leave comments on this issue - you can document private definitions with --document-private-items, this issue isn't meant to track all issues related to private items. If you'd like a better UI for it that distinguishes private and public items, feel free to comment on #68022 with the UI you think would be helpful.