Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

minor: fix documentation of new features #823

Merged
merged 5 commits into from
Feb 8, 2023
Merged

minor: fix documentation of new features #823

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d3baf04
minor: fix FLE documentation
isabelatkinson Feb 2, 2023
a8bd8c0
fix table
isabelatkinson Feb 3, 2023
98b995a
fix feature
isabelatkinson Feb 3, 2023
1ac4cfa
use doc_auto_cfg
isabelatkinson Feb 8, 2023
39384c3
fix feature combos
isabelatkinson Feb 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 4 additions & 7 deletions .evergreen/check-rustdoc.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
14 changes: 11 additions & 3 deletions .evergreen/feature-combinations.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
)
18 changes: 17 additions & 1 deletion Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for removing this! I forgot :)

# 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"]

Expand Down Expand Up @@ -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"
]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main drawback of this new approach is that we need to keep a manual list of all of our features and be sure to append here as new ones are added. I do think this is still a slight improvement to the current situation, though, as this is an easier change than adding #[cfg(docsrs)] to any public API behind a feature flag.

This becomes much easier if we choose to remove our async-std-related features in the future, as we can just specify to use all features 🙂

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, agreed, definitely prefer this way.

3 changes: 1 addition & 2 deletions src/client/auth/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
12 changes: 4 additions & 8 deletions src/client/options/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>,

Expand Down Expand Up @@ -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>,
}

Expand Down Expand Up @@ -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))
}
Expand Down Expand Up @@ -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)))
}
Expand Down
9 changes: 3 additions & 6 deletions src/compression/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
46 changes: 22 additions & 24 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Comment on lines +67 to +68
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are the two new additions to the table; I realized they were missing. I also removed the "Extra dependencies" column as a lot of the information was outdated/incorrect. If we think this information is valuable then I can go through and fix it, but I'm not sure how useful it is given that users can just look at our Cargo.toml. There's also a risk that it will become out-of-date again in the future if we add/change dependencies and forget to update here. Thoughts?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed this doesn't need to be in the table.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM

//!
//! # Example Usage
//!
Expand Down Expand Up @@ -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))]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is slightly unrelated but I noticed that we can remove this now that our MSRV is higher than 1.55.

#![warn(rustdoc::missing_crate_level_docs)]
#![cfg_attr(
feature = "cargo-clippy",
allow(
Expand All @@ -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")]

Expand All @@ -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;
Expand All @@ -335,8 +336,7 @@ pub(crate) mod runtime;
mod sdam;
mod selection_criteria;
mod srv;
#[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;
Expand All @@ -355,8 +355,6 @@ pub use crate::{
db::Database,
gridfs::{GridFsBucket, GridFsDownloadStream, GridFsUploadStream},
};
#[cfg(feature = "in-use-encryption-unstable")]
pub use ::mongocrypt;

pub use {client::session::ClusterTime, coll::Namespace, index::IndexModel, sdam::public::*};

Expand Down