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 2 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
3 changes: 2 additions & 1 deletion Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,11 +67,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
38 changes: 21 additions & 17 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 @@ -343,7 +345,8 @@ mod test;
#[cfg(feature = "tracing-unstable")]
mod trace;
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't think there's anything here that needs to be exported publicly/documented but let me know if that's wrong, @kmahar.

Copy link
Contributor

Choose a reason for hiding this comment

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

the only thing explicitly in the API around tracing is the tracing_max_document_length_bytes option in ClientOptions. that already has the docsrs annotations and appears to show up correctly in the docs: https://docs.rs/mongodb/2.4.0-beta.1/mongodb/options/struct.ClientOptions.html#structfield.tracing_max_document_length_bytes


#[cfg(feature = "in-use-encryption-unstable")]
#[cfg(any(feature = "in-use-encryption-unstable", docsrs))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "sync", feature = "tokio-sync"))))]
Copy link
Contributor

Choose a reason for hiding this comment

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

I think the second line should be

#[cfg_attr(docsrs, doc(cfg(feature = "in-use-encryption-unstable")))]

(and below).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

whoops, bad copy/paste - fixed

pub use crate::client::csfle::client_encryption;
pub use crate::{
client::{session::ClientSession, Client},
Expand All @@ -355,7 +358,8 @@ pub use crate::{
db::Database,
gridfs::{GridFsBucket, GridFsDownloadStream, GridFsUploadStream},
};
#[cfg(feature = "in-use-encryption-unstable")]
#[cfg(any(feature = "in-use-encryption-unstable", docsrs))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "sync", feature = "tokio-sync"))))]
pub use ::mongocrypt;

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