RUST-998 / RUST-2244 Documentation improvements (#581)

Author: isabelatkinson

src/binary.rs

@@ -1,4 +1,5 @@
-#! Module containing functionality related to BSON binary values.
+//! Contains functionality related to BSON binary values.
+
 mod vector;
 
 use std::fmt::{self, Display};

src/bson.rs

@@ -395,23 +395,20 @@ impl From<oid::ObjectId> for Bson {
 }
 
 #[cfg(feature = "time-0_3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "time-0_3")))]
 impl From<time::OffsetDateTime> for Bson {
     fn from(a: time::OffsetDateTime) -> Bson {
         Bson::DateTime(crate::DateTime::from(a))
     }
 }
 
 #[cfg(feature = "chrono-0_4")]
-#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
 impl<T: chrono::TimeZone> From<chrono::DateTime<T>> for Bson {
     fn from(a: chrono::DateTime<T>) -> Bson {
         Bson::DateTime(crate::DateTime::from(a))
     }
 }
 
 #[cfg(feature = "uuid-1")]
-#[cfg_attr(docsrs, doc(cfg(feature = "uuid-1")))]
 impl From<uuid::Uuid> for Bson {
     fn from(uuid: uuid::Uuid) -> Self {
         Bson::Binary(uuid.into())

src/datetime.rs

@@ -211,7 +211,6 @@ impl crate::DateTime {
     /// Convert the given [`chrono::DateTime`] into a [`bson::DateTime`](DateTime), truncating it to
     /// millisecond precision.
     #[cfg(feature = "chrono-0_4")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
     pub fn from_chrono<T: chrono::TimeZone>(dt: chrono::DateTime<T>) -> Self {
         Self::from_millis(dt.timestamp_millis())
     }
@@ -241,7 +240,6 @@ impl crate::DateTime {
     /// assert_eq!(chrono_big, chrono::DateTime::<chrono::Utc>::MAX_UTC)
     /// ```
     #[cfg(feature = "chrono-0_4")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
     pub fn to_chrono(self) -> chrono::DateTime<Utc> {
         match Utc.timestamp_millis_opt(self.0) {
             LocalResult::Single(dt) => dt,
@@ -324,7 +322,6 @@ impl crate::DateTime {
     /// assert_eq!(time_big, time::PrimitiveDateTime::MIN.assume_utc())
     /// ```
     #[cfg(feature = "time-0_3")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "time-0_3")))]
     pub fn to_time_0_3(self) -> time::OffsetDateTime {
         self.to_time_private()
     }
@@ -453,26 +450,20 @@ impl From<crate::DateTime> for SystemTime {
 }
 
 #[cfg(feature = "chrono-0_4")]
-#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
 impl From<crate::DateTime> for chrono::DateTime<Utc> {
     fn from(bson_dt: DateTime) -> Self {
         bson_dt.to_chrono()
     }
 }
 
 #[cfg(feature = "chrono-0_4")]
-#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
 impl<T: chrono::TimeZone> From<chrono::DateTime<T>> for crate::DateTime {
     fn from(x: chrono::DateTime<T>) -> Self {
         Self::from_chrono(x)
     }
 }
 
 #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
-#[cfg_attr(
-    docsrs,
-    doc(cfg(all(feature = "chrono-0_4", feature = "serde_with-3")))
-)]
 impl<'de> serde_with::DeserializeAs<'de, chrono::DateTime<Utc>> for crate::DateTime {
     fn deserialize_as<D>(deserializer: D) -> std::result::Result<chrono::DateTime<Utc>, D::Error>
     where
@@ -484,7 +475,6 @@ impl<'de> serde_with::DeserializeAs<'de, chrono::DateTime<Utc>> for crate::DateT
 }
 
 #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
-#[cfg_attr(docsrs, doc(cfg(all(feature = "chrono-0_4", feature = "chrono-0_4"))))]
 impl serde_with::SerializeAs<chrono::DateTime<Utc>> for crate::DateTime {
     fn serialize_as<S>(
         source: &chrono::DateTime<Utc>,
@@ -499,23 +489,20 @@ impl serde_with::SerializeAs<chrono::DateTime<Utc>> for crate::DateTime {
 }
 
 #[cfg(feature = "time-0_3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "time-0_3")))]
 impl From<crate::DateTime> for time::OffsetDateTime {
     fn from(bson_dt: DateTime) -> Self {
         bson_dt.to_time_0_3()
     }
 }
 
 #[cfg(feature = "time-0_3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "time-0_3")))]
 impl From<time::OffsetDateTime> for crate::DateTime {
     fn from(x: time::OffsetDateTime) -> Self {
         Self::from_time_0_3(x)
     }
 }
 
 #[cfg(all(feature = "time-0_3", feature = "serde_with-3"))]
-#[cfg_attr(docsrs, doc(cfg(all(feature = "time-0_3", feature = "serde_with-3"))))]
 impl<'de> serde_with::DeserializeAs<'de, time::OffsetDateTime> for crate::DateTime {
     fn deserialize_as<D>(deserializer: D) -> std::result::Result<time::OffsetDateTime, D::Error>
     where
@@ -527,7 +514,6 @@ impl<'de> serde_with::DeserializeAs<'de, time::OffsetDateTime> for crate::DateTi
 }
 
 #[cfg(all(feature = "time-0_3", feature = "serde_with-3"))]
-#[cfg_attr(docsrs, doc(cfg(all(feature = "time-0_3", feature = "chrono-0_4"))))]
 impl serde_with::SerializeAs<time::OffsetDateTime> for crate::DateTime {
     fn serialize_as<S>(
         source: &time::OffsetDateTime,

src/error.rs

@@ -12,6 +12,7 @@ pub use oid::ObjectIdErrorKind;
 pub use uuid::UuidErrorKind;
 pub use value_access::ValueAccessErrorKind;
 
+/// The result type for all methods that can return an error in the `bson` crate.
 pub type Result<T> = std::result::Result<T, Error>;
 
 /// An error that can occur in the `bson` crate.

src/lib.rs

@@ -373,8 +373,9 @@
 //! is, it will only happen in a minor or major version release.
 
 #![allow(clippy::cognitive_complexity, clippy::derive_partial_eq_without_eq)]
-#![doc(html_root_url = "https://docs.rs/bson/2.6.0")]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc(html_root_url = "https://docs.rs/bson/3.0.0")]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![warn(missing_docs)]
 
 #[doc(inline)]
 pub use self::{

src/macros.rs

@@ -449,6 +449,7 @@ macro_rules! serde_conv_doc {
         // https://github.com/jonasbb/serde_with/pull/320
         // https://github.com/jonasbb/serde_with/pull/729
         #[allow(clippy::all)]
+        #[allow(missing_docs)]
         const _:() = {
             impl $m {
                 $vis fn serialize<S>(x: &$t, serializer: S) -> Result<S::Ok, S::Error>

src/raw/document_buf.rs

@@ -85,6 +85,23 @@ impl RawDocumentBuf {
         Ok(Self { data })
     }
 
+    /// Constructs a new [`RawDocumentBuf`], validating _only_ the
+    /// following invariants:
+    ///   * `data` is at least five bytes long (the minimum for a valid BSON document)
+    ///   * the initial four bytes of `data` accurately represent the length of the bytes as
+    ///     required by the BSON spec.
+    ///   * the last byte of `data` is a 0
+    ///
+    /// Note that the internal structure of the bytes representing the
+    /// BSON elements is _not_ validated at all by this method. If the
+    /// bytes do not conform to the BSON spec, then method calls on
+    /// the RawDocument will return Errors where appropriate.
+    ///
+    /// ```
+    /// # use bson::raw::RawDocumentBuf;
+    /// let doc = RawDocumentBuf::decode_from_reader(b"\x05\0\0\0\0".as_slice())?;
+    /// # Ok::<(), bson::error::Error>(())
+    /// ```
     pub fn decode_from_reader<R: std::io::Read>(reader: R) -> Result<Self> {
         let buf = crate::raw::reader_to_vec(reader)?;
         Self::decode_from_bytes(buf)
@@ -333,6 +350,7 @@ impl Borrow<RawDocument> for RawDocumentBuf {
 ///   type Target = BindValue<Self>;
 /// }
 /// ```
+#[allow(missing_docs)]
 pub trait BindRawBsonRef: Sized {
     type Target: BindHelper<Target = Self>;
 

src/raw/iter.rs

@@ -109,6 +109,9 @@ impl<'a> RawIter<'a> {
     }
 }
 
+/// A view into a value contained in a [`RawDocument`] or [`RawDocumentBuf`](crate::RawDocumentBuf).
+/// The underlying bytes of the element are not parsed or validated; call [`RawElement::value`] or
+/// one of the `TryFrom` implementations to convert the element into a BSON value.
 #[derive(Clone)]
 pub struct RawElement<'a> {
     key: &'a CStr,
@@ -118,27 +121,27 @@ pub struct RawElement<'a> {
     size: usize,
 }
 
-impl<'a> TryInto<RawBsonRef<'a>> for RawElement<'a> {
+impl<'a> TryFrom<RawElement<'a>> for RawBsonRef<'a> {
     type Error = Error;
 
-    fn try_into(self) -> Result<RawBsonRef<'a>> {
-        self.value()
+    fn try_from(element: RawElement<'a>) -> Result<Self> {
+        element.value()
     }
 }
 
-impl TryInto<RawBson> for RawElement<'_> {
+impl TryFrom<RawElement<'_>> for RawBson {
     type Error = Error;
 
-    fn try_into(self) -> Result<RawBson> {
-        Ok(self.value()?.to_raw_bson())
+    fn try_from(element: RawElement<'_>) -> Result<Self> {
+        Ok(element.value()?.to_raw_bson())
     }
 }
 
-impl TryInto<Bson> for RawElement<'_> {
+impl TryFrom<RawElement<'_>> for Bson {
     type Error = Error;
 
-    fn try_into(self) -> Result<Bson> {
-        self.value()?.to_raw_bson().try_into()
+    fn try_from(element: RawElement<'_>) -> Result<Self> {
+        element.value()?.to_raw_bson().try_into()
     }
 }
 
@@ -157,18 +160,23 @@ impl<'a> RawElement<'a> {
         })
     }
 
+    /// The size of the element.
     pub fn size(&self) -> usize {
         self.size
     }
 
+    /// The document key the element corresponds to.
     pub fn key(&self) -> &'a CStr {
         self.key
     }
 
+    /// The type of the element.
     pub fn element_type(&self) -> ElementType {
         self.kind
     }
 
+    /// Parses this element into a [`RawBsonRef`] and returns an error if the underlying bytes are
+    /// invalid.
     pub fn value(&self) -> Result<RawBsonRef<'a>> {
         Ok(match self.kind {
             ElementType::Null => RawBsonRef::Null,
@@ -270,6 +278,8 @@ impl<'a> RawElement<'a> {
         })
     }
 
+    /// Parses this element into [`RawBson`], replacing any invalid UTF-8 strings with the Unicode
+    /// replacement character. Returns an error if the underlying bytes are invalid.
     pub fn value_utf8_lossy(&self) -> Result<RawBson> {
         match self.value_utf8_lossy_inner()? {
             Some(v) => Ok(v.into()),

src/serde_helpers.rs

@@ -13,7 +13,6 @@ use std::{
 /// - [`object_id::AsHexString`] — converts an [`crate::oid::ObjectId`] to and from a hex string.
 /// - [`object_id::FromHexString`] — converts a hex string to and from an [`crate::oid::ObjectId`].
 #[cfg(feature = "serde_with-3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "serde_with-3")))]
 pub mod object_id {
     use crate::{macros::serde_conv_doc, oid::ObjectId};
     use serde::{Deserialize, Deserializer, Serialize, Serializer};
@@ -85,7 +84,6 @@ pub mod object_id {
 /// - [`datetime::FromTime03OffsetDateTime`] — converts a [`time::OffsetDateTime`] to and from a
 ///   [`crate::DateTime`].
 #[cfg(feature = "serde_with-3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "serde_with-3")))]
 pub mod datetime {
     use crate::{macros::serde_conv_doc, DateTime};
     use chrono::Utc;
@@ -177,7 +175,6 @@ pub mod datetime {
 
     #[cfg(feature = "chrono-0_4")]
     serde_conv_doc!(
-        #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
         /// Converts a [`chrono::DateTime`] to and from a [`DateTime`].
         /// ```rust
         /// # #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
@@ -205,7 +202,6 @@ pub mod datetime {
 
     #[cfg(feature = "time-0_3")]
     serde_conv_doc!(
-        #[cfg_attr(docsrs, doc(cfg(feature = "time-0_3")))]
         /// Converts a [`time::OffsetDateTime`] to and from a [`DateTime`].
         /// ```rust
         /// # #[cfg(all(feature = "time-0_3", feature = "serde_with-3"))]
@@ -239,7 +235,6 @@ pub mod datetime {
 /// - [`timestamp::AsU32`] — converts a [`crate::Timestamp`] to and from a `u32`.
 /// - [`timestamp::FromU32`] — converts a `u32` to and from a [`crate::Timestamp`].
 #[cfg(feature = "serde_with-3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "serde_with-3")))]
 pub mod timestamp {
     use crate::{macros::serde_conv_doc, Timestamp};
     use serde::{Deserialize, Deserializer, Serialize, Serializer};
@@ -319,7 +314,6 @@ pub mod timestamp {
 /// - [`u32::AsI32`] — converts a `u32` to and from an `i32`.
 /// - [`u32::AsI64`] — converts a `u32` to and from an `i64`.
 #[cfg(feature = "serde_with-3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "serde_with-3")))]
 pub mod u32 {
     use crate::macros::serde_conv_doc;
     use serde::{Deserialize, Deserializer, Serialize, Serializer};
@@ -421,7 +415,6 @@ pub mod u32 {
 /// - [`u64::AsI32`] — converts a `u64` to and from an `i32`.
 /// - [`u64::AsI64`] — converts a `u64` to and from an `i64`.
 #[cfg(feature = "serde_with-3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "serde_with-3")))]
 pub mod u64 {
     use crate::macros::serde_conv_doc;
     use serde::{Deserialize, Deserializer, Serialize, Serializer};
@@ -533,7 +526,6 @@ pub mod u64 {
 /// - [`uuid_1::AsPythonLegacyBinary`] — serializes a [`uuid::Uuid`] as a [`crate::Binary`] in the
 ///   legacy Python driver UUID format.
 #[cfg(all(feature = "serde_with-3", feature = "uuid-1"))]
-#[cfg_attr(docsrs, doc(cfg(all(feature = "serde_with-3", feature = "uuid-1"))))]
 pub mod uuid_1 {
     use crate::macros::serde_conv_doc;
     use serde::{Deserialize, Deserializer, Serialize, Serializer};
@@ -681,13 +673,11 @@ macro_rules! as_binary_mod {
         use $uu;
 
         /// Serializes a Uuid as a Binary.
-        #[cfg_attr(docsrs, doc($feat))]
         pub fn serialize<S: Serializer>(val: &Uuid, serializer: S) -> Result<S::Ok, S::Error> {
             crate::uuid::Uuid::from(*val).serialize(serializer)
         }
 
         /// Deserializes a Uuid from a Binary.
-        #[cfg_attr(docsrs, doc($feat))]
         pub fn deserialize<'de, D>(deserializer: D) -> Result<Uuid, D::Error>
         where
             D: Deserializer<'de>,
@@ -707,14 +697,12 @@ macro_rules! as_legacy_binary_mod {
         use $uu;
 
         /// Serializes a Uuid as a Binary in the legacy UUID format.
-        #[cfg_attr(docsrs, doc($feat))]
         pub fn serialize<S: Serializer>(val: &Uuid, serializer: S) -> Result<S::Ok, S::Error> {
             let binary = Binary::from_uuid_with_representation(crate::uuid::Uuid::from(*val), $rep);
             binary.serialize(serializer)
         }
 
         /// Deserializes a Uuid from a Binary in the legacy UUID format.
-        #[cfg_attr(docsrs, doc($feat))]
         pub fn deserialize<'de, D>(deserializer: D) -> Result<Uuid, D::Error>
         where
             D: Deserializer<'de>,