From 46ea3183e7eafb595e95c34f1e8cc0f966bc950c Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Tue, 5 Aug 2025 13:55:57 +0100 Subject: [PATCH 1/2] RUST-1985 Update bson toplevel rustdoc --- src/lib.rs | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index ce6af55c..5b824bbf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -64,9 +64,10 @@ //! | `chrono-0_4` | Enable support for v0.4 of the [`chrono`](https://docs.rs/chrono/0.4) crate in the public API. | no | //! | `uuid-1` | Enable support for v1.x of the [`uuid`](https://docs.rs/uuid/1.x) crate in the public API. | no | //! | `time-0_3` | Enable support for v0.3 of the [`time`](https://docs.rs/time/0.3) crate in the public API. | no | +//! | `serde` | Enable integration with the [`serde`](https://docs.rs/serde/) serialization/deserialization framework. | no | //! | `serde_with-3` | Enable [`serde_with`](https://docs.rs/serde_with/3.x) 3.x integrations for [`DateTime`] and [`Uuid`]. | no | //! | `serde_path_to_error` | Enable support for error paths via integration with [`serde_path_to_error`](https://docs.rs/serde_path_to_err/latest). This is an unstable feature and any breaking changes to `serde_path_to_error` may affect usage of it via this feature. | no | -//! | `compat-3-0-0` | Required for future compatibility if default features are disabled. | no | +//! | `compat-3-0-0` | Required for future compatibility if default features are disabled. | yes | //! | `large_dates` | Increase the supported year range for some `bson::DateTime` utilities from +/-9,999 (inclusive) to +/-999,999 (inclusive). Note that enabling this feature can impact performance and introduce parsing ambiguities. | no | //! | `serde_json-1` | Enable support for v1.x of the [`serde_json`](https://docs.rs/serde_json/1.x) crate in the public API. | no | //! @@ -169,12 +170,13 @@ //! let error = doc.get_i64("i32"); // Err(...) //! ``` //! -//! ## Modeling BSON with strongly typed data structures +//! ## Integration with `serde` //! //! While it is possible to work with documents and BSON values directly, it will often introduce a //! lot of boilerplate for verifying the necessary keys are present and their values are the correct -//! types. [`serde`](https://serde.rs/) provides a powerful way of mapping BSON data into Rust data structures largely -//! automatically, removing the need for all that boilerplate. +//! types. Enabling the `serde` feature provides integration with the [`serde`](https://serde.rs/) +//! crate that maps BSON data into Rust data structs largely automatically, removing the need for +//! all that boilerplate. //! //! e.g.: //! ```rust @@ -223,6 +225,64 @@ //! failing field. This feature does incur a small CPU and memory overhead during (de)serialization //! and should be enabled with care in performance-sensitive environments. //! +//! ### Embedding BSON Value Types +//! +//! The `serde` feature also enables implementations of [`Serialize`](serde::Serialize) and +//! [`Deserialize`](serde::Deserialize) for the Rust types provided by this crate that represent +//! BSON values, allowing them to be embedded in domain-specific structs as appropriate: +//! ```rust +//! use serde::{Deserialize, Serialize}; +//! use bson::{bson, Bson, oid::ObjectId}; +//! +//! #[derive(Serialize, Deserialize)] +//! struct Person { +//! id: ObjectId, +//! name: String, +//! age: i32, +//! phones: Vec, +//! } +//! +//! let bson_data: Bson = bson!({ +//! "id": ObjectId::new(), +//! "name": "John Doe", +//! "age": 43, +//! "phones": [ +//! "+44 1234567", +//! "+44 2345678" +//! ] +//! }); +//! +//! let person: Person = bson::deserialize_from_bson(bson_data).unwrap(); +//! ``` +//! +//! ### Encoding vs. Serialization +//! +//! With the `serde` feature enabled, a BSON document can be converted to its wire-format byte +//! representation in multiple ways: +//! ```rust +//! # fn wrapper() -> bson::Result<()> { +//! use bson::{doc, serialize_to_vec}; +//! let my_document = doc! { "hello": "bson" }; +//! let encoded = my_document.to_vec()?; +//! let serialized = serialize_to_vec(&my_document)?; +//! # Ok(()) +//! # } +//! # wrapper() +//! ``` +//! +//! We recommend that, where possible, documents be converted to byte form using the encoding +//! methods ([`Document::to_vec`]/[`Document::to_writer`]); this is more efficient as it avoids +//! the intermediate `serde` data model representation. This also applies to decoding; prefer +//! [`Document::from_reader`] over [`deserialize_from_reader`] / [`deserialize_from_slice`]. +//! +//! ### Serializer Compatibility +//! +//! The implementations of [`Serialize`](serde::Serialize) and [`Deserialize`](serde::Deserialize) +//! for BSON value types are tested with the `serde` \[de\]serializers provided by this crate and by +//! the `serde_json` crate. Compatibility with formats provided by other crates is not guaranteed +//! and the data produced by serializing BSON values to other formats may change when this crate is +//! updated. +//! //! ## Working with Extended JSON //! //! MongoDB Extended JSON (extJSON) is a format of JSON that allows for the encoding From 962c17d76058e9f7ad43f692c7d7efc720fa6e41 Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Tue, 5 Aug 2025 14:10:29 +0100 Subject: [PATCH 2/2] fix doctest --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5b824bbf..011fddb9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -260,14 +260,14 @@ //! With the `serde` feature enabled, a BSON document can be converted to its wire-format byte //! representation in multiple ways: //! ```rust -//! # fn wrapper() -> bson::Result<()> { +//! # fn wrapper() -> bson::error::Result<()> { //! use bson::{doc, serialize_to_vec}; //! let my_document = doc! { "hello": "bson" }; //! let encoded = my_document.to_vec()?; //! let serialized = serialize_to_vec(&my_document)?; //! # Ok(()) //! # } -//! # wrapper() +//! # wrapper().unwrap(); //! ``` //! //! We recommend that, where possible, documents be converted to byte form using the encoding