Please document your Cargo features
mcclure opened this issue · comments
- I have looked for existing issues (including closed) about this
Bug Report
Version
0.8.4
Platform
Debian trixie but not relevant
Crates
axum
Description
I cargo add axum. It does the normal features printout.
It enables: form, http1, json, matched-path, original-uri, query, tokio, tower-log, tracing.
It disables: __private, __private_docs, http2, macros, multipart, ws
I think: What are these? What's "tower-log" exactly?
I pull your docs.rs page up. Oh, neat, there's a features page! I read it.
https://docs.rs/crate/axum/latest/features#tower-log
This is… not helpful.
Expected behavior:
Please document what all "user-serviceable" Cargo features do. That is, explain why we might want to enable (or disable) them, and for features that are "internal" and should not be touched by end users, please say so.
It is documented here. What you found is an auto-generated page that every crate has and as far as I know is not customizable. See e.g. tokio.
I don't think we need to explicitly document that features starting in __private are, well, private and should not be used and might be changed without warning.
If you have suggestions on how to improve the docs, feel free to continue this issue or send a PR with hat you think the docs should contain.
Sorry I missed this! I agree the __private-named features are self-documented and don't need to be included.