private/hidden features

[ehuss]

It can sometimes be useful to have a feature that you do not want users to use.

docs.rs has a convention that features prefixed with an underscore are not displayed in its UI. Looking through crates.io, I found the following packages declaring features with a leading underscore: https://gist.github.com/ehuss/c2c759067266d530712fc98afcb8513d. The majority look like they are intended to be hidden or internal only, but some are ambiguous.

To some degree, the need for this has been alleviated with the introduction of dep: prefixes which remove the implicit feature created by optional dependencies. However, there are still some use cases.

Some example use cases may be:

• Testing and CI-only features. For example, deny-warnings
• Docs-specific features (TODO: add a concrete example, can this be covered by doc(cfg)?)
• TODO: add more use cases here (summarize the features in the linked gist above)

It is not clear what restrictions a private/hidden feature should have. Not displaying them in the UI and documentation seems useful, but are there other restrictions that can be added? One option is to prevent the use of the feature in a [dependencies] table and only enabled via the CLI or other features in the [features] table, but I'm concerned that rules out some use cases (see gist for some examples).

Proposed syntax:

[features.foobar]
public = false   # or maybe hidden?

I'm opening this issue to track this feature request, but this isn't something we will likely pursue in the near term. This will require an RFC to explore the design in more detail.

See also:

• Previous request: Cargo should allow features/optional-dependencies to be private or public, private by default #7769
• Ivy has a visibility attribute for its configurations
• deprecated features: Feature Request: A way to deprecate features #7130
• feature descriptions: Allow adding a description for features #4956
• unstable features: stable/unstable/nightly-only features #10881

[kornelski]

docs.rs already hides features with a __ prefix, and this is a de-facto standard it in the ecosystem. I think this could simply be documented as the official way of having hidden/internal features.

[ia0]

docs.rs already hides features with a __ prefix, and this is a de-facto standard it in the ecosystem. I think this could simply be documented as the official way of having hidden/internal features.

May I ask a code pointer where this is implemented and example of crates that do that? I tried to git grep __ crates and I get no results. I also tried cargo doc but I guess it's a docs.rs specific functionality so the behavior can't be replicated with cargo doc.

[Nemo157]

May I ask a code pointer where this is implemented and example of crates that do that?

It's actually just an _ prefix, not doubled.

https://github.com/rust-lang/docs.rs/blob/37fa77264f3b08dff432c082cbd412361d89245c/src/web/features.rs#L123
https://github.com/rust-lang/docs.rs/blob/37fa77264f3b08dff432c082cbd412361d89245c/src/db/types.rs#L17

One example crate doing so is stylish, it has the _tests feature in the Cargo.toml which doesn't appear in the docs.rs features page.

[ia0]

Thanks @Nemo157 ! So what I can see from the code, this is only for the list of features, it is still shown in the documentation itself when using doc_auto_cfg (for example when an internal/private/hidden feature is used to enable an item, which usually happens for modules where the internal feature represents any(...) of all features enabling stuff inside the module). I'll wait for a more proper solution like rust-lang/rfcs#3487 then and probably keep prefixing my internal features with internal- instead of _ until then.

[Nemo157]

Yeah, it's only docs.rs that is using this convention. rustdoc (for doc_auto_cfg) and rustc (for diagnostics) will likely not do anything themselves and instead rely on cargo passing a flag to inform them of what cfg's are considered public vs. private, if this is ever implemented (and at that point docs.rs will also switch to asking cargo for this metadata).