Rust: Add option to include private definition in the documentation.
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.
nwin
All 15 comments
I'm -1. You can use regular comments for internal documentation.
steveklabnik
on 2 Jul 2014
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.
alexcrichton
on 2 Jul 2014
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.
nwin
on 2 Jul 2014
Hm it appears that they seem to no longer work! reopening.
alexcrichton
on 2 Jul 2014
I鈥檇 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鈥檛 know very well.
SimonSapin
on 26 Sep 2014
+1. Writing a library, would benefit from being able to see private documentation while I work.
drewcrawford
on 29 Jan 2015
It does look like the workaround
--no-defaults --passes "collapse-docs" --passes "unindent-comments"
works. (Need multiple invocations for "passes").
Recommend close.
drewcrawford
on 29 Jan 2015
@drewcrawford are these rustdoc arguments? Can cargo doc be made to use them?
SimonSapin
on 29 Jan 2015
They're rustdoc arguments. cargo doc can't be taught them, but I'd encourage you to comment in https://github.com/rust-lang/cargo/issues/331 on that topic.
drewcrawford
on 29 Jan 2015
We turned this on on http://doc.servo.org/ . It鈥檚 better, but not ideal: all use and extern crate statements show up as well. It鈥檚 pretty noisy. https://github.com/rust-lang/rust/issues/27104
SimonSapin
on 18 Jul 2015
@alexcrichton, could you edit https://github.com/rust-lang/rust/issues/15347#issuecomment-47828041 ?
--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鈥檛 understand. https://github.com/servo/servo/pull/6668 I鈥檓 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.
SimonSapin
on 20 Jul 2015
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.
gnzlbg
on 8 Sep 2016
I agree with gnzlbg. Sometimes it is good to be able to search.
KalitaAlexey
on 8 Sep 2016
It's something that does not change how official documentation is handled, but that could help a bunch of us.
Razican
on 8 Sep 2016
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!".
gnzlbg
on 8 Sep 2016
Related issues
zhendongsu
路
3Comments
Robbepop
路
3Comments
dtolnay
路
3Comments
mcarton
路
3Comments
pedrohjordao
路
3Comments
Most helpful comment
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!".