misc. cargo doc improvements. #153
Merged
Conversation
This file contains 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
cpu
force-pushed
the
cpu-cargo-doc-touchups
branch
from
6041ad2
to
cd396c6
Compare
Thanks for the review. I believe I addressed all of your comments. |
Matches language across the `permitted_subtrees` and `excluded_subtrees` rustdoc comments for the `NameConstraints` struct.
Updates the crate internal rustdoc comments for the various OID constants so that: * each uses the same format of rustdoc comment. * each has the name the OID uses in the cited doc. * each has a citation link to the defining doc. * each citation link uses the ASN.1 module definition, not the doc section explaining the usage of the associated feature.
Previously `cargo doc` was being invoked in the per-platform CI jobs. This feels unnecessary since no documentation items are gated per-platform and we can rely on the upstream `cargo doc` tool owners to test for general doc generation platform compatibility. In this commit the `cargo doc` invocation is moved to a dedicated job. This also allows shifting the `RUSTDOCFLAGS` env var from a global env var to one scoped to just the job that requires it. We continue to test doc generation using the stable, beta, nightly and MSRV rust versions.
This commit updates the `cargo doc` CI job to run the tool with `--document-private-items`, testing that cargo doc comments on crate internal items are free from error. These comments, while not part of the public API docs, can be helpful for crate developers and should be kept tidy where they exist.
The upstream `docs.rs` website uses the nightly release of the Rust compiler when building project docs. That means we can opt in to the `doc_auto_cfg` feature to have documentation items automatically mention the required crate features where appropriate. This has the advantages of: * Using a nice styled UI element for the requirements. * Keeping the feature requirements in-sync with the docs automatically. Since this feature requires the nightly toolchain we customize the CI environment so that it is enabled only for the nightly channel. [0]: https://docs.rs/about/builds
Now that we've enabled `doc_auto_cfg` these comments are redundant with the auto-generated `docs.rs` notes about required features.
cpu
force-pushed
the
cpu-cargo-doc-touchups
branch
from
cd396c6
to
bf82826
Compare
|
@est31 Just wanted to mention that I enabled the "require merge queue" setting for the repository. It's convenient to be able to queue PRs to automatically merge when CI passes (after the required reviews are in) vs. having to babysit their progress. As usual, repository administrators can bypass this requirement. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Small improvements to the existing rustdocs. I recommend reviewing commit-by-commit.
src/key_pair.rsflagged by beta rust doc.src/oid.rscomments.CertificateSigningRequest, removing an allow for missing docs.--document-private-itemsto the CI rust doc job to catch crate-internal doc errs.doc_auto_cfgto get automatic feature requirement display in the doc.rs docsdoc_auto_cfg's automatic support.