Skip to content
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.

Sign up for GitHub

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

Jump to bottom

cargo doc: add option to document only public items for binary crates #7963

Open
dima74 opened this issue Mar 4, 2020 · 2 comments
Open

cargo doc: add option to document only public items for binary crates #7963

dima74 opened this issue Mar 4, 2020 · 2 comments
Labels
C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` Command-doc S-needs-team-input Status: Needs input from team on whether/how to proceed.

Comments

@dima74
Copy link

dima74 commented Mar 4, 2020

Describe the problem you are trying to solve

#7593 enables --document-private-items flag by default for binary crates. As stated in the PR:

We should also probably add a --document-only-public-items flag or something like that if we change the default behavior. Otherwise users have no way to not document private items for binary crates. Right? -> We can do it later

Describe the solution you'd like

Add flag like --document-only-public-items which can be used for binary crates to disable flag --document-private-items (which is enabled by default)
@dima74 dima74 added the C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` label Mar 4, 2020
@ehuss ehuss mentioned this issue May 23, 2020
Closed
Qix- added a commit to Qix-/cargo that referenced this issue Aug 12, 2022
@Qix-
Allow --document-private-items to accept =yes|no
c43c1b1 
Fixes rust-lang#7963.

Previously, --document-private-items was only a 'truthy' flag,
and was enabled in rust-lang#7593 for binary targets by default. However,
this prevented any means of *disabling* this functionality for
binary targets, hence rust-lang#7963.

This change does a few things. It first adds a new argument
parser type called `yesno_flag()` that is a wrapper around
a few `clap::Arg` settings to use the built-in `BoolishValueParser`
in a way that allows for the `--flag` to return `true`, as well
as an optional `=no` or `=yes` (or `=1`, `=off`, etc.) to explicitly
set it to `true` or `false`.

Then, the internal field for passing the private member documentation
flag to rustdoc was changed to an `Option<bool>` to treat `None`
as the automatic project type detection, and a `Some` value to
override the behavior outright.

This change should be entirely backwards compatible.
@Qix- Qix- mentioned this issue Aug 12, 2022
Closed
Qix- added a commit to Qix-/cargo that referenced this issue Aug 12, 2022
@Qix-
Allow --document-private-items to accept =yes|no
ed49e86 
Fixes rust-lang#7963.

Previously, --document-private-items was only a 'truthy' flag,
and was enabled in rust-lang#7593 for binary targets by default. However,
this prevented any means of *disabling* this functionality for
binary targets, hence rust-lang#7963.

This change does a few things. It first adds a new argument
parser type called `yesno_flag()` that is a wrapper around
a few `clap::Arg` settings to use the built-in `BoolishValueParser`
in a way that allows for the `--flag` to return `true`, as well
as an optional `=no` or `=yes` (or `=1`, `=off`, etc.) to explicitly
set it to `true` or `false`.

Then, the internal field for passing the private member documentation
flag to rustdoc was changed to an `Option<bool>` to treat `None`
as the automatic project type detection, and a `Some` value to
override the behavior outright.

This change should be entirely backwards compatible.
@Qix-
Copy link

Qix- commented Aug 12, 2022

Took a whack at this in #10979. Hopefully that solves the need :)

Qix- added a commit to Qix-/cargo that referenced this issue Aug 12, 2022
@Qix-
Allow --document-private-items to accept =yes|no
23c973e 
Fixes rust-lang#7963.

Previously, --document-private-items was only a 'truthy' flag,
and was enabled in rust-lang#7593 for binary targets by default. However,
this prevented any means of *disabling* this functionality for
binary targets, hence rust-lang#7963.

This change does a few things. It first adds a new argument
parser type called `yesno_flag()` that is a wrapper around
a few `clap::Arg` settings to use the built-in `BoolishValueParser`
in a way that allows for the `--flag` to return `true`, as well
as an optional `=no` or `=yes` (or `=1`, `=off`, etc.) to explicitly
set it to `true` or `false`.

Then, the internal field for passing the private member documentation
flag to rustdoc was changed to an `Option<bool>` to treat `None`
as the automatic project type detection, and a `Some` value to
override the behavior outright.

This change should be entirely backwards compatible.
@tom25519
Copy link

tom25519 commented Jun 7, 2023

Hi, just wanted to bump this, as it's definitely still something I would find useful. Generating documentation for a binary package can be useful to someone navigating a codebase for the first time, but unfortunately, certain macros tend to leave undocumented private items all over a crate (e.g: Tracing leaves private CALLSITE and META statics wherever any of its macros are used). The reasoning for closing #10979 was that #[doc(hidden)] can be used, but obviously in such cases, this is not possible. Plus tagging everything with #[doc(hidden)] gets kind of annoying anyway. Would the Cargo team be interested in merging a PR to address this?

@weihanglo weihanglo added the S-needs-team-input Status: Needs input from team on whether/how to proceed. label Jun 8, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` Command-doc S-needs-team-input Status: Needs input from team on whether/how to proceed.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Allow --document-private-items to accept =yes|no Qix-/cargo
5 participants
@ehuss @Qix- @dima74 @weihanglo @tom25519