cbor: prepare for publishing as standalone crate

- Add an example of usage
- Add a minimal README, including the example code
- Document public items
- Add more info to Cargo.toml

libraries/cbor/src/macros.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Convenience macros for working with CBOR values.
+
 use crate::values::Value;
 use alloc::vec;
 use core::cmp::Ordering;
@@ -110,6 +112,7 @@ pub fn destructure_cbor_map_peek_value(
     }
 }
 
+/// Assert that the keys in a vector of key-value pairs are in canonical order.
 #[macro_export]
 macro_rules! assert_sorted_keys {
     // Last key

libraries/cbor/src/reader.rs

@@ -12,11 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Functionality for deserializing CBOR data into values.
+
 use super::values::{Constants, SimpleValue, Value};
 use crate::{cbor_array_vec, cbor_bytes_lit, cbor_map_collection, cbor_text, cbor_unsigned};
 use alloc::str;
 use alloc::vec::Vec;
 
+/// Possible errors from a deserialization operation.
 #[derive(Debug, PartialEq)]
 pub enum DecoderError {
     UnsupportedMajorType,
@@ -32,6 +35,8 @@ pub enum DecoderError {
     OutOfRangeIntegerValue,
 }
 
+/// Deserialize CBOR binary data to produce a single [`Value`], expecting that there
+/// is no additional data.
 pub fn read(encoded_cbor: &[u8]) -> Result<Value, DecoderError> {
     let mut reader = Reader::new(encoded_cbor);
     let value = reader.decode_complete_data_item(Reader::MAX_NESTING_DEPTH)?;

libraries/cbor/src/values.rs

@@ -12,24 +12,34 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Types for expressing CBOR values.
+
 use super::writer::write;
 use alloc::string::{String, ToString};
 use alloc::vec::Vec;
 use core::cmp::Ordering;
 
+/// Possible CBOR values.
 #[derive(Clone, Debug)]
 pub enum Value {
+    /// Unsigned integer value (uint).
     Unsigned(u64),
-    // We only use 63 bits of information here.
+    /// Signed integer value (nint). Only 63 bits of information are used here.
     Negative(i64),
+    /// Byte string (bstr).
     ByteString(Vec<u8>),
+    /// Text string (tstr).
     TextString(String),
+    /// Array/tuple of values.
     Array(Vec<Value>),
+    /// Map of key-value pairs.
     Map(Vec<(Value, Value)>),
     // TAG is omitted
+    /// Simple value.
     Simple(SimpleValue),
 }
 
+/// Specific simple CBOR values.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub enum SimpleValue {
     FalseValue = 20,
@@ -38,20 +48,30 @@ pub enum SimpleValue {
     Undefined = 23,
 }
 
+/// Constant values required for CBOR encoding.
 pub struct Constants {}
 
 impl Constants {
+    /// Number of bits used to shift left the major type of a CBOR type byte.
     pub const MAJOR_TYPE_BIT_SHIFT: u8 = 5;
+    /// Mask to retrieve the additional information held in a CBOR type bytes,
+    /// ignoring the major type.
     pub const ADDITIONAL_INFORMATION_MASK: u8 = 0x1F;
+    /// Additional information value that indicates the largest inline value.
     pub const ADDITIONAL_INFORMATION_MAX_INT: u8 = 23;
+    /// Additional information value indicating that a 1-byte length follows.
     pub const ADDITIONAL_INFORMATION_1_BYTE: u8 = 24;
+    /// Additional information value indicating that a 2-byte length follows.
     pub const ADDITIONAL_INFORMATION_2_BYTES: u8 = 25;
+    /// Additional information value indicating that a 4-byte length follows.
     pub const ADDITIONAL_INFORMATION_4_BYTES: u8 = 26;
+    /// Additional information value indicating that an 8-byte length follows.
     pub const ADDITIONAL_INFORMATION_8_BYTES: u8 = 27;
 }
 
 impl Value {
-    // For simplicity, this only takes i64. Construct directly for the last bit.
+    /// Create an appropriate CBOR integer value (uint/nint).
+    /// For simplicity, this only takes i64. Construct directly for the last bit.
     pub fn integer(int: i64) -> Value {
         if int >= 0 {
             Value::Unsigned(int as u64)
@@ -60,6 +80,7 @@ impl Value {
         }
     }
 
+    /// Create a CBOR boolean simple value.
     pub fn bool_value(b: bool) -> Value {
         if b {
             Value::Simple(SimpleValue::TrueValue)
@@ -68,6 +89,7 @@ impl Value {
         }
     }
 
+    /// Return the major type for the [`Value`].
     pub fn type_label(&self) -> u8 {
         // TODO use enum discriminant instead when stable
         // https://github.com/rust-lang/rust/issues/60553
@@ -128,6 +150,7 @@ impl PartialEq for Value {
 }
 
 impl SimpleValue {
+    /// Create a simple value from its encoded value.
     pub fn from_integer(int: u64) -> Option<SimpleValue> {
         match int {
             20 => Some(SimpleValue::FalseValue),
@@ -193,7 +216,9 @@ impl From<bool> for Value {
     }
 }
 
+/// Trait that indicates that a type can be converted to a CBOR [`Value`].
 pub trait IntoCborValue {
+    /// Convert `self` into a CBOR [`Value`], consuming it along the way.
     fn into_cbor_value(self) -> Value;
 }
 
@@ -206,7 +231,9 @@ where
     }
 }
 
+/// Trait that indicates that a type can be converted to a CBOR [`Option<Value>`].
 pub trait IntoCborValueOption {
+    /// Convert `self` into a CBOR [`Option<Value>`], consuming it along the way.
     fn into_cbor_value_option(self) -> Option<Value>;
 }
 

libraries/cbor/src/writer.rs

@@ -12,9 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Functionality for serializing CBOR values into bytes.
+
 use super::values::{Constants, Value};
 use alloc::vec::Vec;
 
+/// Convert a [`Value`] to serialized CBOR data, consuming it along the way and appending to the provided vector.
+/// Returns a `bool` indicating whether conversion succeeded.
 pub fn write(value: Value, encoded_cbor: &mut Vec<u8>) -> bool {
     let mut writer = Writer::new(encoded_cbor);
     writer.encode_cbor(value, Writer::MAX_NESTING_DEPTH)