From 76ffb2ef8f13fd0bee6516b012379e4fdbca1408 Mon Sep 17 00:00:00 2001 From: Isabel Atkinson Date: Wed, 8 Feb 2023 15:41:14 -0500 Subject: [PATCH] minor: fix documentation of new features (#823) --- .evergreen/check-rustdoc.sh | 11 +++---- .evergreen/feature-combinations.sh | 14 +++++++-- Cargo.toml | 18 +++++++++++- src/client/auth/mod.rs | 3 +- src/client/options/mod.rs | 12 +++----- src/compression/mod.rs | 9 ++---- src/lib.rs | 46 ++++++++++++++---------------- 7 files changed, 62 insertions(+), 51 deletions(-) diff --git a/.evergreen/check-rustdoc.sh b/.evergreen/check-rustdoc.sh index dc178ea03..7329f4006 100755 --- a/.evergreen/check-rustdoc.sh +++ b/.evergreen/check-rustdoc.sh @@ -14,14 +14,11 @@ source ./.evergreen/configure-rust.sh source ./.evergreen/feature-combinations.sh # build with all available features to ensure all optional dependencies are brought in too. -for ((i = 0; i < ${#FEATURE_COMBINATIONS[@]}; i++)); do - cargo +nightly build ${FEATURE_COMBINATIONS[$i]} -done +cargo +nightly build $ADDITIONAL_FEATURES cargo clean chmod -R 555 ${CARGO_HOME}/registry/src -for ((i = 0; i < ${#FEATURE_COMBINATIONS[@]}; i++)); do - cargo +nightly rustdoc ${FEATURE_COMBINATIONS[$i]} -- -D warnings --cfg docsrs -done - +# this invocation mirrors the way docs.rs builds our documentation (see the [package.metadata.docs.rs] section +# in Cargo.toml). +cargo +nightly rustdoc $ADDITIONAL_FEATURES -- -D warnings --cfg docsrs diff --git a/.evergreen/feature-combinations.sh b/.evergreen/feature-combinations.sh index 19af725a4..4ec6ec4e2 100755 --- a/.evergreen/feature-combinations.sh +++ b/.evergreen/feature-combinations.sh @@ -1,10 +1,18 @@ #!/bin/bash +# Only default features. +export NO_FEATURES='' +# async-std-related features that conflict with the library's default features. +export ASYNC_STD_FEATURES='--no-default-features --features async-std-runtime,sync' +# All additional features that do not conflict with the default features. New features added to the library should also be added to this list. +export ADDITIONAL_FEATURES='--features tokio-sync,zstd-compression,snappy-compression,zlib-compression,openssl-tls,aws-auth,tracing-unstable,in-use-encryption-unstable' + + # Array of feature combinations that, in total, provides complete coverage of the driver. # This is useful for linting tasks where we want to get coverage of all features. # Since some of our features are mutually exclusive we cannot just use --all-features. export FEATURE_COMBINATIONS=( - '' # default features - '--no-default-features --features async-std-runtime,sync' # features that conflict w/ default features - '--features tokio-sync,zstd-compression,snappy-compression,zlib-compression,openssl-tls,aws-auth,tracing-unstable,in-use-encryption-unstable' # additive features + "$NO_FEATURES" + "$ASYNC_STD_FEATURES" + "$ADDITIONAL_FEATURES" ) diff --git a/Cargo.toml b/Cargo.toml index 116937369..42d777bba 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -26,6 +26,8 @@ exclude = [ "tests/**", ] +# NOTE: any new features added to this list should also be added to the features +# list in the [package.metadata.docs.rs] section below. [features] default = ["tokio-runtime"] tokio-runtime = [ @@ -67,11 +69,12 @@ zstd-compression = ["zstd"] zlib-compression = ["flate2"] snappy-compression = ["snap"] +# Enables support for client-side field level encryption and queryable encryption. # The In Use Encryption API is unstable and may have backwards-incompatible changes in minor version updates. in-use-encryption-unstable = ["mongocrypt", "rayon", "num_cpus"] -# DO NOT USE; see https://jira.mongodb.org/browse/RUST-580 for the status of tracing/logging support in the Rust driver. # Enables support for emitting tracing events. +# The tracing API is unstable and may have backwards-incompatible changes in minor version updates. # TODO: pending https://github.com/tokio-rs/tracing/issues/2036 stop depending directly on log. tracing-unstable = ["tracing", "log"] @@ -185,3 +188,16 @@ regex = "1.6.0" [package.metadata.docs.rs] rustdoc-args = ["--cfg", "docsrs"] +# async-std-runtime and sync are excluded here because they conflict with the default features. +# Neither feature has any unique documentation associated with it, so we do not need to +# include them in our documentation build. +features = [ + "tokio-sync", + "zstd-compression", + "snappy-compression", + "zlib-compression", + "openssl-tls", + "aws-auth", + "tracing-unstable", + "in-use-encryption-unstable" +] \ No newline at end of file diff --git a/src/client/auth/mod.rs b/src/client/auth/mod.rs index 2c47b24f4..0127dd050 100644 --- a/src/client/auth/mod.rs +++ b/src/client/auth/mod.rs @@ -82,8 +82,7 @@ pub enum AuthMechanism { /// /// Note: Only server versions 4.4+ support AWS authentication. Additionally, the driver only /// supports AWS authentication with the tokio runtime. - #[cfg(any(feature = "aws-auth", docsrs))] - #[cfg_attr(docsrs, doc(cfg(feature = "aws-auth")))] + #[cfg(feature = "aws-auth")] MongoDbAws, } diff --git a/src/client/options/mod.rs b/src/client/options/mod.rs index 0e5768fee..d5f1a6d98 100644 --- a/src/client/options/mod.rs +++ b/src/client/options/mod.rs @@ -536,8 +536,7 @@ pub struct ClientOptions { /// Note that in cases where truncation occurs the output will not be valid JSON. /// /// The default value is 1000. - #[cfg(any(feature = "tracing-unstable", docsrs))] - #[cfg_attr(docsrs, doc(cfg(feature = "tracing-unstable")))] + #[cfg(feature = "tracing-unstable")] #[builder(default)] pub tracing_max_document_length_bytes: Option, @@ -938,8 +937,7 @@ pub struct TlsOptions { /// is invalid. /// /// The default value is to error on invalid hostnames. - #[cfg(any(feature = "openssl-tls", docsrs))] - #[cfg_attr(docsrs, doc(cfg(feature = "openssl-tls")))] + #[cfg(feature = "openssl-tls")] pub allow_invalid_hostnames: Option, } @@ -1072,8 +1070,7 @@ impl ClientOptions { /// This method will be present if the `sync` feature is enabled. It's otherwise identical to /// [the async version](#method.parse) - #[cfg(any(feature = "sync", feature = "tokio-sync", docsrs))] - #[cfg_attr(docsrs, doc(cfg(any(feature = "sync", feature = "tokio-sync"))))] + #[cfg(any(feature = "sync", feature = "tokio-sync"))] pub fn parse(s: impl AsRef) -> Result { runtime::block_on(Self::parse_uri(s.as_ref(), None)) } @@ -1102,8 +1099,7 @@ impl ClientOptions { /// This method will be present if the `sync` feature is enabled. It's otherwise identical to /// [the async version](#method.parse_with_resolver_config) - #[cfg(any(feature = "sync", feature = "tokio-sync", docsrs))] - #[cfg_attr(docsrs, doc(cfg(any(feature = "sync", feature = "tokio-sync"))))] + #[cfg(any(feature = "sync", feature = "tokio-sync"))] pub fn parse_with_resolver_config(uri: &str, resolver_config: ResolverConfig) -> Result { runtime::block_on(Self::parse_uri(uri, Some(resolver_config))) } diff --git a/src/compression/mod.rs b/src/compression/mod.rs index f1bbdc647..7f0071ea2 100644 --- a/src/compression/mod.rs +++ b/src/compression/mod.rs @@ -65,24 +65,21 @@ impl CompressorId { pub enum Compressor { /// Zstd compressor. Requires Rust version 1.54. /// See [`Zstd`](http://facebook.github.io/zstd/zstd_manual.html) for more information - #[cfg(any(feature = "zstd-compression", docsrs))] - #[cfg_attr(docsrs, doc(cfg(feature = "zstd-compression")))] + #[cfg(feature = "zstd-compression")] Zstd { /// Zstd compression level level: Option, }, /// Zlib compressor. /// See [`Zlib`](https://zlib.net/) for more information. - #[cfg(any(feature = "zlib-compression", docsrs))] - #[cfg_attr(docsrs, doc(cfg(feature = "zlib-compression")))] + #[cfg(feature = "zlib-compression")] Zlib { /// Zlib compression level level: Option, }, /// Snappy compressor. /// See [`Snappy`](http://google.github.io/snappy/) for more information. - #[cfg(any(feature = "snappy-compression", docsrs))] - #[cfg_attr(docsrs, doc(cfg(feature = "snappy-compression")))] + #[cfg(feature = "snappy-compression")] Snappy, } diff --git a/src/lib.rs b/src/lib.rs index c00520212..22b182be2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -49,21 +49,23 @@ //! //! ### All Feature flags //! -//! | Feature | Description | Extra dependencies | Default | -//! |:---------------------|:--------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------|:--------| -//! | `tokio-runtime` | Enable support for the `tokio` async runtime | `tokio` 1.0 with the `full` feature | yes | -//! | `async-std-runtime` | Enable support for the `async-std` runtime | `async-std` 1.0 | no | -//! | `sync` | Expose the synchronous API (`mongodb::sync`), using an async-std backend. Cannot be used with the `tokio-runtime` feature flag. | `async-std` 1.0 | no | -//! | `tokio-sync` | Expose the synchronous API (`mongodb::sync`), using a tokio backend. Cannot be used with the `async-std-runtime` feature flag. | `tokio` 1.0 with the `full` feature | no | -//! | `aws-auth` | Enable support for the MONGODB-AWS authentication mechanism. | `reqwest` 0.11 | no | -//! | `bson-uuid-0_8` | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API of the re-exported `bson` crate. | n/a | no | -//! | `bson-uuid-1` | Enable support for v1.x of the [`uuid`](docs.rs/uuid/1.0) crate in the public API of the re-exported `bson` crate. | n/a | no | -//! | `bson-chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API of the re-exported `bson` crate. | n/a | no | -//! | `bson-serde_with` | Enable support for the [`serde_with`](docs.rs/serde_with/latest) crate in the public API of the re-exported `bson` crate. | `serde_with` 1.0 | no | -//! | `zlib-compression` | Enable support for compressing messages with [`zlib`](https://zlib.net/) | `flate2` 1.0 | no | -//! | `zstd-compression` | Enable support for compressing messages with [`zstd`](http://facebook.github.io/zstd/). This flag requires Rust version 1.54. | `zstd` 0.9.0 | no | -//! | `snappy-compression` | Enable support for compressing messages with [`snappy`](http://google.github.io/snappy/) | `snap` 1.0.5 | no | -//! | `openssl-tls` | Switch TLS connection handling to use ['openssl'](https://docs.rs/openssl/0.10.38/). | `openssl` 0.10.38 | no | +//! | Feature | Description | Default | +//! |:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------| +//! | `tokio-runtime` | Enable support for the `tokio` async runtime. | yes | +//! | `async-std-runtime` | Enable support for the `async-std` runtime. | no | +//! | `sync` | Expose the synchronous API (`mongodb::sync`), using an async-std backend. Cannot be used with the `tokio-runtime` feature flag. | no | +//! | `tokio-sync` | Expose the synchronous API (`mongodb::sync`), using a tokio backend. Cannot be used with the `async-std-runtime` feature flag. | no | +//! | `aws-auth` | Enable support for the MONGODB-AWS authentication mechanism. | no | +//! | `bson-uuid-0_8` | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API of the re-exported `bson` crate. | no | +//! | `bson-uuid-1` | Enable support for v1.x of the [`uuid`](docs.rs/uuid/1.0) crate in the public API of the re-exported `bson` crate. | no | +//! | `bson-chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API of the re-exported `bson` crate. | no | +//! | `bson-serde_with` | Enable support for the [`serde_with`](docs.rs/serde_with/latest) crate in the public API of the re-exported `bson` crate. | no | +//! | `zlib-compression` | Enable support for compressing messages with [`zlib`](https://zlib.net/). | no | +//! | `zstd-compression` | Enable support for compressing messages with [`zstd`](http://facebook.github.io/zstd/). | no | +//! | `snappy-compression` | Enable support for compressing messages with [`snappy`](http://google.github.io/snappy/). | no | +//! | `openssl-tls` | Switch TLS connection handling to use [`openssl`](https://docs.rs/openssl/0.10.38/). | no | +//! | `in-use-encryption-unstable` | Enable support for client-side field level encryption and queryable encryption. This API is unstable and may be subject to breaking changes in minor releases. | no | +//! | `tracing-unstable` | Enable support for emitting [`tracing`](https://docs.rs/tracing/latest/tracing/) events. This API is unstable and may be subject to breaking changes in minor releases. | no | //! //! # Example Usage //! @@ -288,10 +290,7 @@ //! it will only happen in a minor or major version release. #![warn(missing_docs)] -// `missing_crate_level_docs` was renamed with a `rustdoc::` prefix in rustc 1.55, but isn't -// supported in the MSRV. -// TODO: remove the wrapping cfg_attr if/when the MSRV is 1.55+. -#![cfg_attr(docsrs, warn(rustdoc::missing_crate_level_docs))] +#![warn(rustdoc::missing_crate_level_docs)] #![cfg_attr( feature = "cargo-clippy", allow( @@ -302,7 +301,7 @@ clippy::derive_partial_eq_without_eq ) )] -#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] #![cfg_attr(test, type_length_limit = "80000000")] #![doc(html_root_url = "https://docs.rs/mongodb/2.4.0")] @@ -313,6 +312,8 @@ compile_error!("The `aws-auth` feature flag is only supported on the tokio runti pub mod options; pub use ::bson; +#[cfg(feature = "in-use-encryption-unstable")] +pub use ::mongocrypt; mod bson_util; pub mod change_stream; @@ -337,8 +338,7 @@ mod selection_criteria; mod srv; #[cfg(feature = "tracing-unstable")] mod trace; -#[cfg(any(feature = "sync", feature = "tokio-sync", docsrs))] -#[cfg_attr(docsrs, doc(cfg(any(feature = "sync", feature = "tokio-sync"))))] +#[cfg(any(feature = "sync", feature = "tokio-sync"))] pub mod sync; #[cfg(test)] mod test; @@ -355,8 +355,6 @@ pub use crate::{ }; #[cfg(feature = "in-use-encryption-unstable")] pub use crate::client::csfle::client_encryption; -#[cfg(feature = "in-use-encryption-unstable")] -pub use ::mongocrypt; pub use {client::session::ClusterTime, coll::Namespace, index::IndexModel, sdam::public::*};