minor: fix documentation of new features (#823)

isabelatkinson · isabelatkinson · commit 76ffb2ef8f13 · 2023-02-09T10:42:04.000-05:00
diff --git 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
@@ -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
@@ -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"
+]
diff --git 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
@@ -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<usize>,
 
@@ -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<bool>,
 }
 
@@ -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<str>) -> Result<Self> {
         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<Self> {
         runtime::block_on(Self::parse_uri(uri, Some(resolver_config)))
     }
diff --git 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<i32>,
     },
     /// 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<i32>,
     },
     /// 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
@@ -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::*};
 

Original file line number	Diff line number	Diff line change
`@@ -82,8 +82,7 @@ pub enum AuthMechanism {`
`82`	`82`	`///`
`83`	`83`	`/// Note: Only server versions 4.4+ support AWS authentication. Additionally, the driver only`
`84`	`84`	`/// supports AWS authentication with the tokio runtime.`
`85`		`- #[cfg(any(feature = "aws-auth", docsrs))]`
`86`		`- #[cfg_attr(docsrs, doc(cfg(feature = "aws-auth")))]`
	`85`	`+ #[cfg(feature = "aws-auth")]`
`87`	`86`	`MongoDbAws,`
`88`	`87`	`}`
`89`	`88`