Enable all features in documentation and utilize doc_auto_cfg#670
Merged
algesten merged 1 commit intoalgesten:mainfrom Oct 11, 2023
Merged
Enable all features in documentation and utilize doc_auto_cfg#670algesten merged 1 commit intoalgesten:mainfrom
doc_auto_cfg#670algesten merged 1 commit intoalgesten:mainfrom
Conversation
Contributor
Author
|
Note that I'm thinking of yoinking these |
6 tasks
033195d to
0f5e7b6
Compare
Testing all features instead of just a specific set makes it possible for the CI to spot various mistakes in currently-untested doc comments, such as those behind the `http-interop` feature. More importantly, enabling _all features_ on docs.rs as well massively helps visibility in available features and functionality to the end user. And `doc_cfg`/ `doc_auto_cfg` automatically provide them the right information block with a (list of) feature(s) they need to enable to get access to a certain type or function. Note that this requires a `nightly` feature and is hence behind a `--cfg` flag that is only enabled when building for docs.rs (using `nightly`). It can be reproduced locally via `RUSTDOCFLAGS=--cfg=docsrs cargo +nightly doc`. Additionally the CI script is updated to pass `-Dwarnings` to `rustdoc` so that it can adequately fail the CI when incorrect documentation is encountered.
0f5e7b6 to
21a2553
Compare
Owner
|
Thanks! |
Contributor
Author
|
Oh. I did not expect the CI to succeed just yet because I have a bunch of warnings locally on Rust 1.73 😦 |
MarijnS95
added a commit
to MarijnS95/ureq
that referenced
this pull request
Oct 11, 2023
…tems I added `--all-features` in algesten#670 without removing `--no-default-features` which now has no effect anymore. In addition it is useful to make sure that documentation on private items also adheres to valid intradoc, and somewhat strangely enabling this also causes additional lint warnings on public documentation...
Contributor
Author
|
Trying to sort that out in #673 |
MarijnS95
added a commit
to MarijnS95/ureq
that referenced
this pull request
Oct 11, 2023
…tems I added `--all-features` in algesten#670 without removing `--no-default-features` which now has no effect anymore. In addition it is useful to make sure that documentation on private items also adheres to valid intradoc, and somewhat strangely enabling this also causes additional lint warnings on public documentation...
algesten
pushed a commit
that referenced
this pull request
Oct 11, 2023
…tems I added `--all-features` in #670 without removing `--no-default-features` which now has no effect anymore. In addition it is useful to make sure that documentation on private items also adheres to valid intradoc, and somewhat strangely enabling this also causes additional lint warnings on public documentation...
MarijnS95
added a commit
to MarijnS95/ureq
that referenced
this pull request
Oct 11, 2023
As mentioned in algesten#670 (comment) this sort of documentation is superfluous now that `doc_cfg`/ `doc_auto_cfg` **automatically** generates colored blocks in the documentation denoting what `cfg`s (including features) need to be met in order to enable a symbol. In addition the `http` feature only exists to turn on the `http` crate, while the type conversions in the `http_interop.rs` module are only provided behind the `http-interop` feature. The `charset` feature documentation is left in place, because that affects additional functionality deeper down inside the `send_string()` function.
algesten
pushed a commit
that referenced
this pull request
Oct 16, 2023
As mentioned in #670 (comment) this sort of documentation is superfluous now that `doc_cfg`/ `doc_auto_cfg` **automatically** generates colored blocks in the documentation denoting what `cfg`s (including features) need to be met in order to enable a symbol. In addition the `http` feature only exists to turn on the `http` crate, while the type conversions in the `http_interop.rs` module are only provided behind the `http-interop` feature. The `charset` feature documentation is left in place, because that affects additional functionality deeper down inside the `send_string()` function.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Testing all features instead of just a specific set makes it possible for the CI to spot various mistakes in currently-untested doc comments, such as those behind the
http-interopfeature. More importantly, enabling all features on docs.rs as well massively helps visibility in available features and functionality to the end user. Anddoc_cfg/doc_auto_cfgautomatically provide them the right information block with a (list of) feature(s) they need to enable to get access to a certain type or function.Note that this requires a
nightlyfeature and is hence behind a--cfgflag that is only enabled when building for docs.rs (usingnightly). It can be reproduced locally viaRUSTDOCFLAGS=--cfg=docsrs cargo +nightly doc.Additionally the CI script is updated to pass
-Dwarningstorustdocso that it can adequately fail the CI when incorrect documentation is encountered.