Cargo: A standard schema for crate feature flags documentation?

community
1

I have an idea about Cargo features documentation. A toml schema that crate authors-maintainers can add to Cargo.toml, or it's own file like features.toml that explains to the user of the crate what exactly to expect when adding that feature flag. So IDE autocompletion and documentation tools can scan the file and produce useful info about the feature while editing the application's own Cargo.toml file, or searching for the crate with cargo search.

Something in the lines of:

  • This feature adds this exact functionality to your application
  • This feature modifies code in this way. Disabling this and enabling that.
  • This feature will increase the binary size approximately this much
  • This feature has these gotchas so be careful
  • This feature is standalone and you pay only if you use it or parts of it
  • This feature depends on this and that
  • This feature is unstable-experimental, use it for testing only

These are the things that came to my mind in a quick brainstorm. They're in no way the final draft proposal :slight_smile:

And maybe something like this is already in the works? But if not:

How can I pass this proposal or whatever it is to Rust people? Is there an spmc channel to the higher up?

2
  • First you should search the issues and PRs of the Rust, RFCs, and Cargo repositories to see what has been done before.
  • Then, if you have questions about the current state of things or “what do you think of the implementation consequences of adding this?”, post them on Zulip.
  • If you have a complete proposal, you would create a RFC PR.
    • But RFCs need to define exactly what is being added, and thoroughly justified with things like “prior art” and “alternatives to this design”. If you’re not there yet but you have a sketch of your idea more precise than “features should have documentation!”, write it up and post it on Rust Internals where you can get some feedback without an expectation of readiness.
1 Like
3

As a minimum I would suggest using the cfg_doc feature: doc_cfg - The Rust Unstable Book

1 Like
4

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.