diff --git a/.evergreen/check-rustdoc.sh b/.evergreen/check-rustdoc.sh new file mode 100755 index 000000000..b4fe8cce6 --- /dev/null +++ b/.evergreen/check-rustdoc.sh @@ -0,0 +1,8 @@ +#!/bin/sh + +set -o errexit + +. ~/.cargo/env +cargo rustdoc -- -D warnings +cargo rustdoc --no-default-features --features async-std-runtime -- -D warnings +cargo rustdoc --no-default-features --features sync -- -D warnings diff --git a/.evergreen/config.yml b/.evergreen/config.yml index 8ed3f11d7..51b595bd5 100644 --- a/.evergreen/config.yml +++ b/.evergreen/config.yml @@ -497,6 +497,16 @@ functions: ${PREPARE_SHELL} .evergreen/check-clippy.sh + "check rustdoc": + - command: shell.exec + type: test + params: + shell: bash + working_dir: "src" + script: | + ${PREPARE_SHELL} + .evergreen/check-rustdoc.sh + "upload-mo-artifacts": - command: shell.exec params: @@ -1115,6 +1125,10 @@ tasks: commands: - func: "check clippy" + - name: "check-rustdoc" + commands: + - func: "check rustdoc" + axes: @@ -1342,4 +1356,5 @@ buildvariants: tasks: - name: "check-clippy" - name: "check-rustfmt" + - name: "check-rustdoc" diff --git a/Cargo.toml b/Cargo.toml index 0fd3d690e..a6c552b3f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [package] -authors = ["Saghm Rossi ", "Patrick Freed "] +authors = ["Saghm Rossi ", "Patrick Freed ", "Isabel Atkinson "] description = "The official MongoDB driver for Rust" edition = "2018" documentation = "https://docs.rs/mongodb" @@ -8,7 +8,7 @@ repository = "https://github.com/mongodb/mongo-rust-driver" license = "Apache-2.0" readme = "README.md" name = "mongodb" -version = "1.1.1" +version = "1.2.0" exclude = [ "etc/**", @@ -24,12 +24,17 @@ default = ["tokio-runtime"] tokio-runtime = ["tokio/dns", "tokio/macros", "tokio/rt-core", "tokio/tcp", "tokio/rt-threaded", "tokio/time", "reqwest", "serde_bytes"] async-std-runtime = ["async-std", "async-std/attributes"] sync = ["async-std-runtime"] +# The bson/u2i feature enables automatic conversion from unsigned to signed types during +# serialization. This feature is intended for use when serializing data types in third-party crates +# whose implementation cannot be changed; otherwise, it is preferred to use the helper functions +# provided in the bson::serde_helpers module. +bson-u2i = ["bson/u2i"] [dependencies] async-trait = "0.1.24" base64 = "0.11.0" bitflags = "1.1.0" -bson = "1.1.0" +bson = "1.2.0" chrono = "0.4.7" derivative = "2.1.1" err-derive = "0.2.3" diff --git a/README.md b/README.md index 649760157..1e9ed2269 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ This repository contains the officially supported MongoDB Rust driver, a client | Driver Version | Required Rust Version | |:--------------:|:---------------------:| | master | 1.43+ | +| 1.2.x | 1.43+ | | 1.1.x | 1.43+ | | 1.0.x | 1.43+ | | 0.11.x | 1.43+ | @@ -45,7 +46,7 @@ https://github.com/rust-lang/rust/issues/75992. The driver is available on [crates.io](https://crates.io/crates/mongodb). To use the driver in your application, simply add it to your project's `Cargo.toml`. ```toml [dependencies] -mongodb = "1.1.1" +mongodb = "1.2.0" ``` #### Configuring the async runtime @@ -54,7 +55,7 @@ The driver supports both of the most popular async runtime crates, namely [`toki For example, to instruct the driver to work with [`async-std`](https://crates.io/crates/async-std), add the following to your `Cargo.toml`: ```toml [dependencies.mongodb] -version = "1.1.1" +version = "1.2.0" default-features = false features = ["async-std-runtime"] ``` @@ -63,7 +64,7 @@ features = ["async-std-runtime"] The driver also provides a blocking sync API. To enable this, add the `"sync"` feature to your `Cargo.toml`: ```toml [dependencies.mongodb] -version = "1.1.1" +version = "1.2.0" default-features = false features = ["sync"] ``` @@ -270,9 +271,11 @@ You can use `rustup` to install them both: rustup component add clippy --toolchain stable rustup component add rustfmt --toolchain nightly ``` -To run the linter tests, run the `check-clippy.sh` and `check-rustfmt.sh` scripts in the `.evergreen` directory: +Our linter tests also use `rustdoc` to verify that all necessary documentation is present and properly formatted. `rustdoc` is included in the standard Rust distribution. + +To run the linter tests, run the `check-clippy.sh`, `check-rustfmt.sh`, and `check-rustdoc.sh` scripts in the `.evergreen` directory: ```bash -bash .evergreen/check-clippy.sh && bash .evergreen/check-rustfmt.sh +bash .evergreen/check-clippy.sh && bash .evergreen/check-rustfmt.sh && bash .evergreen/check-rustdoc.sh ``` ## Continuous Integration diff --git a/src/client/auth/mod.rs b/src/client/auth/mod.rs index 18547ca99..0bf904b43 100644 --- a/src/client/auth/mod.rs +++ b/src/client/auth/mod.rs @@ -181,6 +181,7 @@ impl AuthMechanism { } } + /// Returns this `AuthMechanism` as a string. pub fn as_str(&self) -> &'static str { match self { AuthMechanism::ScramSha1 => SCRAM_SHA_1_STR, diff --git a/src/client/options/mod.rs b/src/client/options/mod.rs index 88f09569b..b79db6b66 100644 --- a/src/client/options/mod.rs +++ b/src/client/options/mod.rs @@ -142,6 +142,7 @@ impl Hash for StreamAddress { } impl StreamAddress { + /// Parses an address string into a `StreamAddress`. pub fn parse(address: &str) -> Result { let mut parts = address.split(':'); @@ -209,7 +210,7 @@ impl fmt::Display for StreamAddress { /// Specifies the server API version to declare #[derive(Clone, Debug, PartialEq)] #[non_exhaustive] -pub enum ServerApiVersion { +pub(crate) enum ServerApiVersion { Version1, } @@ -251,7 +252,7 @@ impl<'de> Deserialize<'de> for ServerApiVersion { #[derive(Clone, Debug, Deserialize, PartialEq, TypedBuilder)] #[serde(rename_all = "camelCase")] #[non_exhaustive] -pub struct ServerApi { +pub(crate) struct ServerApi { /// The version string of the declared API version pub version: ServerApiVersion, @@ -402,8 +403,8 @@ pub struct ClientOptions { /// The declared API version /// /// The default value is to have no declared API version - #[builder(default)] - pub server_api: Option, + #[builder(default, skip)] + pub(crate) server_api: Option, /// The amount of time the Client should attempt to select a server for an operation before /// timing outs @@ -509,7 +510,10 @@ struct ClientOptionsParser { /// [`Client`](../struct.Client.html) performs. #[derive(Clone, Debug, Deserialize, PartialEq)] pub enum Tls { + /// Enable TLS with the specified options. Enabled(TlsOptions), + + /// Disable TLS. Disabled, } @@ -566,6 +570,7 @@ impl ServerCertVerifier for NoCertVerifier { } impl TlsOptions { + /// Converts `TlsOptions` into a rustls::ClientConfig. pub fn into_rustls_config(self) -> Result { let mut config = rustls::ClientConfig::new(); diff --git a/src/cmap/options.rs b/src/cmap/options.rs index b368abdcb..229f59606 100644 --- a/src/cmap/options.rs +++ b/src/cmap/options.rs @@ -85,8 +85,8 @@ pub struct ConnectionPoolOptions { /// The declared API version /// /// The default value is to have no declared API version - #[builder(default)] - pub server_api: Option, + #[builder(skip, default)] + pub(crate) server_api: Option, /// The options specifying how a TLS connection should be configured. If `tls_options` is /// `None`, then TLS will not be used for the connections. @@ -118,7 +118,6 @@ impl ConnectionPoolOptions { .max_idle_time(options.max_idle_time) .max_pool_size(options.max_pool_size) .min_pool_size(options.min_pool_size) - .server_api(options.server_api.clone()) .tls_options(options.tls_options()) .wait_queue_timeout(options.wait_queue_timeout) .build() diff --git a/src/db/options.rs b/src/db/options.rs index 9d82ad57e..9f38765d3 100644 --- a/src/db/options.rs +++ b/src/db/options.rs @@ -118,7 +118,9 @@ pub enum ValidationLevel { #[serde(rename_all = "camelCase")] #[non_exhaustive] pub enum ValidationAction { + /// Return an error if inserted documents do not pass the validation. Error, + /// Raise a warning if inserted documents do not pass the validation. Warn, } diff --git a/src/error.rs b/src/error.rs index 2be402ec0..20b30106f 100644 --- a/src/error.rs +++ b/src/error.rs @@ -218,6 +218,7 @@ impl std::ops::Deref for Error { } /// The types of errors that can occur. +#[allow(missing_docs)] #[derive(Debug, Error)] #[non_exhaustive] pub enum ErrorKind { @@ -560,7 +561,11 @@ impl BulkWriteFailure { #[derive(Clone, Debug)] #[non_exhaustive] pub enum WriteFailure { + /// An error that occurred due to not being able to satisfy a write concern. WriteConcernError(WriteConcernError), + + /// An error that occurred during a write operation that wasn't due to being unable to satisfy a + /// write concern. WriteError(WriteError), } diff --git a/src/lib.rs b/src/lib.rs index 58270d986..66ce94fab 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -70,6 +70,9 @@ //! # } //! ``` +#![warn(missing_docs)] +#![warn(missing_crate_level_docs)] + #![cfg_attr( feature = "cargo-clippy", allow( diff --git a/src/runtime/mod.rs b/src/runtime/mod.rs index ae4ca9395..55053b390 100644 --- a/src/runtime/mod.rs +++ b/src/runtime/mod.rs @@ -46,6 +46,7 @@ impl AsyncRuntime { /// If the runtime is still running, this will return a handle to the background task. /// Otherwise, it will return `None`. As a result, this must be called from an async block /// or function running on a runtime. + #[allow(clippy::unnecessary_wraps)] pub(crate) fn spawn(self, fut: F) -> Option> where F: Future + Send + 'static, diff --git a/src/selection_criteria.rs b/src/selection_criteria.rs index e91af5138..7fad83fc3 100644 --- a/src/selection_criteria.rs +++ b/src/selection_criteria.rs @@ -93,12 +93,15 @@ pub type Predicate = Arc bool>; /// option and will be sent to the server as an integer number of seconds. /// /// See the [MongoDB docs](https://docs.mongodb.com/manual/core/read-preference) for more details. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq)] pub enum ReadPreference { /// Only route this operation to the primary. Primary, + /// Only route this operation to a secondary. Secondary { options: ReadPreferenceOptions }, + /// Route this operation to the primary if it's available, but fall back to the secondaries if /// not. PrimaryPreferred { options: ReadPreferenceOptions }, @@ -179,6 +182,7 @@ pub struct HedgedReadOptions { } impl HedgedReadOptions { + /// Creates a new `HedgedReadOptions` with the given value for `enabled`. pub fn with_enabled(enabled: bool) -> Self { Self { enabled } } diff --git a/src/test/client.rs b/src/test/client.rs index dcc3f5ac0..4e2af6ab6 100644 --- a/src/test/client.rs +++ b/src/test/client.rs @@ -107,7 +107,7 @@ async fn connection_drop_during_read() { async fn server_selection_timeout_message() { let _guard: RwLockReadGuard<()> = LOCK.run_concurrently().await; - if !CLIENT_OPTIONS.repl_set_name.is_some() { + if CLIENT_OPTIONS.repl_set_name.is_none() { return; } diff --git a/src/test/spec/unified_runner/test_file.rs b/src/test/spec/unified_runner/test_file.rs index 6149b52f3..d94a4d450 100644 --- a/src/test/spec/unified_runner/test_file.rs +++ b/src/test/spec/unified_runner/test_file.rs @@ -130,7 +130,7 @@ pub struct Client { pub observe_events: Option>, pub ignore_command_monitoring_events: Option>, #[serde(default)] - pub server_api: Option, + pub(crate) server_api: Option, } fn default_uri() -> String { diff --git a/src/test/util/event.rs b/src/test/util/event.rs index f4fa8e200..414ed559a 100644 --- a/src/test/util/event.rs +++ b/src/test/util/event.rs @@ -243,7 +243,7 @@ impl EventClient { EventClient::with_options_and_handler(options, event_handler, collect_server_info).await } - pub async fn with_uri_and_mongos_options( + pub(crate) async fn with_uri_and_mongos_options( uri: &str, use_multiple_mongoses: Option, server_api: Option,