Add doctested examples to most public methods

Author: hoxxep

Diff for: ciborium/src/de/mod.rs

@@ -786,6 +786,24 @@ where
 /// If you want to deserialize faster at the cost of more memory, consider using
 /// [`from_reader_with_buffer`](from_reader_with_buffer) with a larger buffer,
 /// for example 64KB.
+///
+/// # Example
+/// ```rust
+/// use ciborium::from_reader;
+///
+/// #[derive(Debug, serde::Deserialize, Eq, PartialEq)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let cbor = hex::decode("a36161182a61621910686261611901a4").unwrap();
+/// let expected = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let deserialized: Example = from_reader(cbor.as_slice()).unwrap();
+/// assert_eq!(deserialized, expected);
+/// ```
 #[inline]
 pub fn from_reader<T: de::DeserializeOwned, R: Read>(reader: R) -> Result<T, Error<R::Error>>
 where
@@ -798,6 +816,25 @@ where
 /// Deserializes as CBOR from a type with [`impl
 /// ciborium_io::Read`](ciborium_io::Read), using a caller-specific buffer as a
 /// temporary scratch space.
+///
+/// # Example
+/// ```rust
+/// use ciborium::from_reader_with_buffer;
+///
+/// #[derive(Debug, serde::Deserialize, Eq, PartialEq)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let cbor = hex::decode("a36161182a61621910686261611901a4").unwrap();
+/// let expected = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let mut scratch = [0; 8192];
+/// let deserialized: Example = from_reader_with_buffer(cbor.as_slice(), &mut scratch).unwrap();
+/// assert_eq!(deserialized, expected);
+/// ```
 #[inline]
 pub fn from_reader_with_buffer<T: de::DeserializeOwned, R: Read>(
     reader: R,
@@ -820,6 +857,24 @@ where
 /// will result in [`Error::RecursionLimitExceeded`] .
 ///
 /// Set a high recursion limit at your own risk (of stack exhaustion)!
+///
+/// # Example
+/// ```rust
+/// use ciborium::de::from_reader_with_recursion_limit;
+///
+/// #[derive(Debug, serde::Deserialize, Eq, PartialEq)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let cbor = hex::decode("a36161182a61621910686261611901a4").unwrap();
+/// let expected = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let deserialized: Example = from_reader_with_recursion_limit(cbor.as_slice(), 1024).unwrap();
+/// assert_eq!(deserialized, expected);
+/// ```
 #[inline]
 pub fn from_reader_with_recursion_limit<T: de::DeserializeOwned, R: Read>(
     reader: R,

Diff for: ciborium/src/ser/mod.rs

@@ -32,20 +32,35 @@ pub enum CanonicalizationScheme {
 
 #[cfg(feature = "std")]
 impl CanonicalizationScheme {
-    /// Does this canonicalisation scheme require sorting of keys.
+    /// Does this canonicalization scheme require sorting of keys.
     pub fn is_sorting(&self) -> bool {
         matches!(self, Self::Rfc7049 | Self::Rfc8049)
     }
-
-    // pub fn key<K: serde::Serialize>(&self, key: &K) -> Result<Vec<u8>, Error<std::io::Error>> {
-    //     let mut buffer = Vec::new();
-    //     let mut serializer = Serializer::new(&mut buffer, true);
-    //     key.serialize(&mut serializer)?;
-    //     Ok(buffer)
-    // }
 }
 
 /// A serializer for CBOR.
+///
+/// # Example
+/// ```rust
+/// use serde::Serialize;
+/// use ciborium::Serializer;
+/// use ciborium::ser::CanonicalizationScheme;
+///
+/// #[derive(serde::Serialize)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let example = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let mut buffer = Vec::with_capacity(1024);
+/// let mut serializer = Serializer::new(&mut buffer, CanonicalizationScheme::Rfc8049);
+/// example.serialize(&mut serializer).unwrap();
+///
+/// assert_eq!(hex::encode(&buffer), "a36161182a61621910686261611901a4");
+/// ```
 pub struct Serializer<W> {
     encoder: Encoder<W>,
 
@@ -647,6 +662,23 @@ where
 }
 
 /// Serializes as CBOR into `Vec<u8>`.
+///
+/// # Example
+/// ```rust
+/// use ciborium::to_vec;
+///
+/// #[derive(serde::Serialize)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let example = Example { a: 42, aa: 420, b: 4200 };
+/// let bytes = to_vec(&example).unwrap();
+///
+/// assert_eq!(hex::encode(&bytes), "a36161182a6261611901a46162191068");
+/// ```
 #[cfg(feature = "std")]
 #[inline]
 pub fn to_vec<T: ?Sized + ser::Serialize>(value: &T) -> Result<Vec<u8>, Error<std::io::Error>> {
@@ -657,6 +689,24 @@ pub fn to_vec<T: ?Sized + ser::Serialize>(value: &T) -> Result<Vec<u8>, Error<st
 }
 
 /// Canonically serializes as CBOR into `Vec<u8>` with a specified [CanonicalizationScheme].
+///
+/// # Example
+/// ```rust
+/// use ciborium::to_vec_canonical;
+/// use ciborium::ser::CanonicalizationScheme;
+///
+/// #[derive(serde::Serialize)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let example = Example { a: 42, aa: 420, b: 4200 };
+/// let bytes = to_vec_canonical(&example, CanonicalizationScheme::Rfc8049).unwrap();
+///
+/// assert_eq!(hex::encode(&bytes), "a36161182a61621910686261611901a4");
+/// ```
 #[cfg(feature = "std")]
 #[inline]
 pub fn to_vec_canonical<T: ?Sized + ser::Serialize>(value: &T, scheme: CanonicalizationScheme) -> Result<Vec<u8>, Error<std::io::Error>> {
@@ -667,6 +717,25 @@ pub fn to_vec_canonical<T: ?Sized + ser::Serialize>(value: &T, scheme: Canonical
 }
 
 /// Serializes as CBOR into a type with [`impl ciborium_io::Write`](ciborium_io::Write)
+///
+/// # Example
+/// ```rust
+/// use ciborium::into_writer;
+///
+/// #[derive(serde::Serialize)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let example = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let mut bytes = Vec::new();
+/// into_writer(&example, &mut bytes).unwrap();
+///
+/// assert_eq!(hex::encode(&bytes), "a36161182a6261611901a46162191068");
+/// ```
 #[inline]
 pub fn into_writer<T: ?Sized + ser::Serialize, W: Write>(
     value: &T,
@@ -682,6 +751,26 @@ where
 /// Canonically serializes as CBOR into a type with [`impl ciborium_io::Write`](ciborium_io::Write)
 ///
 /// This will sort map keys in output according to a specified [CanonicalizationScheme].
+///
+/// # Example
+/// ```rust
+/// use ciborium::into_writer_canonical;
+/// use ciborium::ser::CanonicalizationScheme;
+///
+/// #[derive(serde::Serialize)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let example = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let mut bytes = Vec::new();
+/// into_writer_canonical(&example, &mut bytes, CanonicalizationScheme::Rfc8049).unwrap();
+///
+/// assert_eq!(hex::encode(&bytes), "a36161182a61621910686261611901a4");
+/// ```
 #[cfg(feature = "std")]
 #[inline]
 pub fn into_writer_canonical<T: ?Sized + ser::Serialize, W: Write>(