Clean up feature/module documentation with docs.rs features #518
Clean up feature/module documentation with docs.rs features #518spacebear21 merged 6 commits intopayjoin:masterfrom
Conversation
`receive` already does this. Make send reflect receive visibility.
Indicate modules enabled by feature flags.
These are encapsulated in the Request impl and pollute the docs.
base64 handling is done inside the state machine now.
Pull Request Test Coverage Report for Build 13059298349Details
💛 - Coveralls |
Describe with a broad brush to improve them from nothing.
| //! | ||
| //! For most use cases, we recommended enabling the `v2` feature, as it is | ||
| //! backwards compatible and provides the most convenient experience for users and implementors. | ||
| #![cfg_attr(feature = "v2", doc = "To use version 2, refer to [`v2`] module documentation.")] |
There was a problem hiding this comment.
Is this supposed to only display if the v2 feature is enabled? I tried with RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-default-features --features=v1 --open but this section still shows up.
There was a problem hiding this comment.
This is wild. I'm getting this --no-default-features disrespect as well, even after pruning RUSTDOCFLAGS and
this from Config.toml.
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]A simpler solution is to ignore module-specific docs at this top level and instead write it in the module's first line, since we'll post that via all-features to docs.rs where the vast majority will go for documentation.
| //! If you specifically need to use | ||
| //! version 1, refer to the [`v1`] module documentation. |
There was a problem hiding this comment.
Relatedly, should this be feature-gated behind the v1 feature being explicitly enabled?
|
I got rid of the feature switched documentation. The primary point of features is to minimize compiled code. Limited API surface is a secondary concern, and our documentation may be explicit about available features even when they're available under specific configuration. |
|
An unrelated Url change snuck into the last commit, otherwise looks good to me. |
|
I was wondering where the hell that file went in my stash ... fixed |
Excessive feature gates lead to needless confusion.
3 participants
run with
RUSTDOCFLAGS="--cfg docsrs" cargo doc --all-features --opensendmodule feature gating toreceivemodule gating. I like this because it makes what's available explicit, and hides stuff you don't want in the default configuration, but I could understand removing if it seems like excessive complexity in cfging (API changing)cfg_attr(this needs the RUSTDOCFLAGS)Discovered these flaws with docs in while addressing #504.