Allow --document-private-items to accept =yes|no

[Qix-]

Fixes #7963.

Previously, --document-private-items was only a 'truthy' flag,
and was enabled in #7593 for binary targets by default. However,
this prevented any means of disabling this functionality for
binary targets, hence #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.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

[Qix-]

There is one downside to this PR that is worth mentioning, and I have no idea how to fix it (perhaps someone well-versed with clap can help).

The added length to the option help text now causes all of the docs to wrap below the option, effectively doubling tripling the help text length and making it nearly unreadable.

Is there a way to extend the gap between the options and the help text?

Before:

        --frozen                    Require Cargo.lock and cache are up to date
        --no-deps                   Don't build documentation for dependencies
        --document-private-items    Document private items
        --locked                    Require Cargo.lock is up to date
    -j, --jobs <N>                  Number of parallel jobs, defaults to # of CPUs

After:

        --frozen
            Require Cargo.lock and cache are up to date

        --no-deps
            Don't build documentation for dependencies

        --document-private-items[=<yes|no>]
            Document private items (the default for binaries)

        --locked
            Require Cargo.lock is up to date

    -j, --jobs <N>
            Number of parallel jobs, defaults to # of CPUs

---

Otherwise, the argument itself could instead be shortened to --private=[yes|no] and --document-private-items could be deprecated. I personally think that's a much better approach but I realize this adds extra effort to deprecate/maintain.

Given that there might be a reason to allow for other visibility selections (i.e. internally pub vs crate pub, the latter of which is currently what "public" means to the documentation filter), perhaps it makes more sense to have a --visibility=private|crate|public flag instead. This would remove the need for yesno_flag() entirely, but would result several more changes in the PR. Happy to make them, though.

[Qix-]

I don't know if I did this right and don't have any idea on how to actually test this. I tried to read the zsh docs on the compdef file format but... wow it's dense. Any guidance would be appreciated.

[ehuss]

Thanks for the PR! Can you say more about what your use case is where you do not want the private items documented? From my perspective, hiding private items in a library makes sense since the library can be used as a dependency which only has access to the public items. However that case doesn't exist for a binary, so whether or not something is public in a binary doesn't really have much consequence.

@epage Would you be able to review this (or at least the clap side of things)?

[Qix-]

The use-case at the time of submission was that only pub members from each respective module would be documented, instead of all of the non -pub members as well. However I realize now that 1) that's not what this PR accomplishes, and 2) using #[doc(hidden)] is a much better approach to this problem, especially when paired with #![deny(missing_docs, clippy::missing_docs_in_private_items)].

Feel free to close (though I also recommend closing #7963 too).

Still curious about the CLI help text formatting issue though, just for curiosity's sake. I fought with that for a while and figured I'd see if someone else knew what was happening.

[ehuss]

OK, will close this out then.

I don't think there is a way to prevent the next-line help stuff. I believe here it uses a hueristic to determine things are too long, and it doesn't look like that can be turned off.

[epage]

Sorry, I missed the mention.

If you don't want overflow prevention in help, you can just turn it off by setting the term width to zero (impl, docs)

[tom25519]

I mentioned this in #7963, but unfortunately the #[doc(hidden)] solution isn't applicable to all cases (e.g: when using Tracing, which has macros which tend to leave undocumented private statics all over the place). I still think there is value in this feature :)