Docs in cloudevents-sdk crate

Signed-off-by: Francesco Guardiani <[email protected]>

Author: slinkydeveloper

Cargo.toml

@@ -11,6 +11,7 @@ repository = "https://github.com/cloudevents/sdk-rust"
 exclude = [
     ".github/*"
 ]
+categories = ["web-programming", "encoding", "data-structures"]
 
 [lib]
 name = "cloudevents"

README.md

@@ -43,8 +43,7 @@ let event = EventBuilderV10::new()
     .id("aaa")
     .source(Url::parse("http://localhost").unwrap())
     .ty("example.demo")
-    .build()
-    .unwrap();
+    .build()?;
 ```
 
 Checkout the examples using our integrations to learn how to send and receive events:

src/event/attributes.rs

@@ -7,7 +7,8 @@ use serde::Serializer;
 use std::fmt;
 use url::Url;
 
-/// Value of a CloudEvent attribute
+/// Enum representing a borrowed value of a CloudEvent attribute.
+/// This represents the types defined in the [CloudEvent spec type system](https://github.com/cloudevents/spec/blob/v1.0/spec.md#type-system)
 #[derive(Debug, PartialEq, Eq)]
 pub enum AttributeValue<'a> {
     SpecVersion(SpecVersion),
@@ -230,20 +231,20 @@ impl AttributesWriter for Attributes {
 }
 
 impl Attributes {
-    pub fn into_v10(self) -> Self {
+    pub(crate) fn into_v10(self) -> Self {
         match self {
             Attributes::V03(v03) => Attributes::V10(v03.into_v10()),
             _ => self,
         }
     }
-    pub fn into_v03(self) -> Self {
+    pub(crate) fn into_v03(self) -> Self {
         match self {
             Attributes::V10(v10) => Attributes::V03(v10.into_v03()),
             _ => self,
         }
     }
 
-    pub fn iter(&self) -> impl Iterator<Item = (&str, AttributeValue)> {
+    pub(crate) fn iter(&self) -> impl Iterator<Item = (&str, AttributeValue)> {
         match self {
             Attributes::V03(a) => AttributesIter::IterV03(a.into_iter()),
             Attributes::V10(a) => AttributesIter::IterV10(a.into_iter()),

src/event/data.rs

@@ -1,6 +1,6 @@
 use serde::export::Formatter;
 use serde_json::Value;
-use std::convert::{Into, TryFrom};
+use std::convert::TryFrom;
 use std::fmt;
 
 /// Event [data attribute](https://github.com/cloudevents/spec/blob/master/spec.md#event-data) representation
@@ -14,40 +14,6 @@ pub enum Data {
     Json(serde_json::Value),
 }
 
-impl Data {
-    /// Create a [`Data`] from a [`Into<Vec<u8>>`].
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use cloudevents::event::Data;
-    ///
-    /// let value = Data::from_base64(b"dmFsdWU=").unwrap();
-    /// assert_eq!(value, Data::Binary(base64::decode("dmFsdWU=").unwrap()));
-    /// ```
-    ///
-    /// [`AsRef<[u8]>`]: https://doc.rust-lang.org/std/convert/trait.AsRef.html
-    /// [`Data`]: enum.Data.html
-    pub fn from_base64<I>(i: I) -> Result<Self, base64::DecodeError>
-    where
-        I: AsRef<[u8]>,
-    {
-        Ok(base64::decode(&i)?.into())
-    }
-
-    pub fn from_binary<I>(content_type: Option<&str>, i: I) -> Result<Self, serde_json::Error>
-    where
-        I: AsRef<[u8]>,
-    {
-        let is_json = is_json_content_type(content_type.unwrap_or("application/json"));
-        if is_json {
-            serde_json::from_slice::<serde_json::Value>(i.as_ref()).map(Data::Json)
-        } else {
-            Ok(Data::Binary(i.as_ref().to_vec()))
-        }
-    }
-}
-
 pub(crate) fn is_json_content_type(ct: &str) -> bool {
     ct.starts_with("application/json") || ct.starts_with("text/json") || ct.ends_with("+json")
 }

src/event/extensions.rs

@@ -6,11 +6,11 @@ use std::fmt;
 #[serde(untagged)]
 /// Represents all the possible [CloudEvents extension](https://github.com/cloudevents/spec/blob/master/spec.md#extension-context-attributes) values
 pub enum ExtensionValue {
-    /// Represents a [`String`](std::string::String) value.
+    /// Represents a [`String`] value.
     String(String),
-    /// Represents a [`bool`](bool) value.
+    /// Represents a [`bool`] value.
     Boolean(bool),
-    /// Represents an integer [`i64`](i64) value.
+    /// Represents an integer [`i64`] value.
     Integer(i64),
 }
 

src/event/mod.rs

@@ -1,3 +1,5 @@
+//! Provides [`Event`] data structure, [`EventBuilder`] and other facilities to work with [`Event`].
+
 mod attributes;
 mod builder;
 mod data;

src/event/spec_version.rs

@@ -5,14 +5,18 @@ use std::fmt;
 
 pub(crate) const SPEC_VERSIONS: [&'static str; 2] = ["0.3", "1.0"];
 
-/// CloudEvent specification version
+/// CloudEvent specification version.
 #[derive(PartialEq, Eq, Hash, Debug, Clone)]
 pub enum SpecVersion {
+    /// CloudEvents v0.3
     V03,
+    /// CloudEvents v1.0
     V10,
 }
 
 impl SpecVersion {
+    /// Returns the string representation of [`SpecVersion`].
+    #[inline]
     pub fn as_str(&self) -> &str {
         match self {
             SpecVersion::V03 => "0.3",
@@ -28,7 +32,7 @@ impl SpecVersion {
             SpecVersion::V10 => &v10::ATTRIBUTE_NAMES,
         }
     }
-    /// Get all attribute names for all Spec versions.
+    /// Get all attribute names for all specification versions.
     /// Note that the result iterator could contain duplicate entries.
     pub fn all_attribute_names() -> impl Iterator<Item = &'static str> {
         vec![SpecVersion::V03, SpecVersion::V10]

src/lib.rs

@@ -1,36 +1,45 @@
 //! This crate implements the [CloudEvents](https://cloudevents.io/) Spec for Rust.
 //!
 //! ```
+//! # use std::error::Error;
+//! # fn main() -> Result<(), Box<dyn Error>> {
 //! use cloudevents::{EventBuilder, AttributesReader, EventBuilderV10};
-//! use chrono::Utc;
+//! use chrono::{Utc, DateTime};
 //! use url::Url;
 //!
 //! let event = EventBuilderV10::new()
 //!     .id("my_event.my_application")
 //!     .source("http://localhost:8080")
 //!     .ty("example.demo")
 //!     .time(Utc::now())
-//!     .build()
-//!     .unwrap();
+//!     .build()?;
 //!
 //! println!("CloudEvent Id: {}", event.id());
-//! println!("CloudEvent Time: {}", event.time().unwrap());
+//! match event.time() {
+//!     Some(t) => println!("CloudEvent Time: {}", t),
+//!     None => println!("CloudEvent Time: None")
+//! }
+//! # Ok(())
+//! # }
 //! ```
 //!
+//! This crate includes:
+//!
+//! * The [`Event`] data structure, to represent CloudEvent (version 1.0 and 0.3)
+//! * The [`EventBuilder`] trait and implementations, to create [`Event`] instances
+//! * The implementation of [`serde::Serialize`] and [`serde::Deserialize`] for [`Event`] to serialize/deserialize CloudEvents to/from JSON
+//! * Traits and utilities in [`message`] to implement Protocol Bindings
+//!
 //! If you're looking for Protocol Binding implementations, look at crates:
 //!
 //! * [cloudevents-sdk-actix-web](https://docs.rs/cloudevents-sdk-actix-web): Integration with [Actix Web](https://github.com/actix/actix-web)
 //! * [cloudevents-sdk-reqwest](https://docs.rs/cloudevents-sdk-reqwest): Integration with [reqwest](https://github.com/seanmonstar/reqwest)
+//! * [cloudevents-sdk-rdkafka](https://docs.rs/cloudevents-sdk-rdkafka): Integration with [rdkafka](https://fede1024.github.io/rust-rdkafka)
 //!
 
-extern crate serde;
-extern crate serde_json;
-extern crate serde_value;
-extern crate snafu;
+#![deny(broken_intra_doc_links)]
 
-/// Provides [`Event`] data structure, [`EventBuilder`] and other facilities to work with [`Event`]
 pub mod event;
-/// Provides facilities to implement Protocol Bindings
 pub mod message;
 
 pub use event::Data;

src/message/deserializer.rs

@@ -2,46 +2,46 @@ use super::{BinarySerializer, Encoding, Error, Result, StructuredSerializer};
 use crate::event::{EventBinarySerializer, EventStructuredSerializer};
 use crate::Event;
 
-/// Deserializer trait for a Message that can be encoded as structured mode
+/// Deserializer trait for a Message that can be encoded as structured mode.
 pub trait StructuredDeserializer
 where
     Self: Sized,
 {
-    /// Deserialize the message to [`StructuredSerializer`]
+    /// Deserialize the message to [`StructuredSerializer`].
     fn deserialize_structured<R: Sized, V: StructuredSerializer<R>>(
         self,
         serializer: V,
     ) -> Result<R>;
 
-    /// Convert this Message to [`Event`]
+    /// Convert this Message to [`Event`].
     fn into_event(self) -> Result<Event> {
         self.deserialize_structured(EventStructuredSerializer {})
     }
 }
 
-/// Deserializer trait for a Message that can be encoded as binary mode
+/// Deserializer trait for a Message that can be encoded as binary mode.
 pub trait BinaryDeserializer
 where
     Self: Sized,
 {
-    /// Deserialize the message to [`BinarySerializer`]
+    /// Deserialize the message to [`BinarySerializer`].
     fn deserialize_binary<R: Sized, V: BinarySerializer<R>>(self, serializer: V) -> Result<R>;
 
-    /// Convert this Message to [`Event`]
+    /// Convert this Message to [`Event`].
     fn into_event(self) -> Result<Event> {
         self.deserialize_binary(EventBinarySerializer::new())
     }
 }
 
-/// Deserializer trait for a Message that can be encoded both in structured mode or binary mode
+/// Deserializer trait for a Message that can be encoded both in structured mode or binary mode.
 pub trait MessageDeserializer
 where
     Self: StructuredDeserializer + BinaryDeserializer + Sized,
 {
-    /// Get this message [`Encoding`]
+    /// Get this message [`Encoding`].
     fn encoding(&self) -> Encoding;
 
-    /// Convert this Message to [`Event`]
+    /// Convert this Message to [`Event`].
     fn into_event(self) -> Result<Event> {
         match self.encoding() {
             Encoding::BINARY => BinaryDeserializer::into_event(self),
@@ -50,7 +50,7 @@ where
         }
     }
 
-    /// Deserialize the message to [`BinarySerializer`]
+    /// Deserialize the message to [`BinarySerializer`].
     fn deserialize_to_binary<R: Sized, T: BinarySerializer<R>>(self, serializer: T) -> Result<R> {
         if self.encoding() == Encoding::BINARY {
             return self.deserialize_binary(serializer);
@@ -59,7 +59,7 @@ where
         return MessageDeserializer::into_event(self)?.deserialize_binary(serializer);
     }
 
-    /// Deserialize the message to [`StructuredSerializer`]
+    /// Deserialize the message to [`StructuredSerializer`].
     fn deserialize_to_structured<R: Sized, T: StructuredSerializer<R>>(
         self,
         serializer: T,
@@ -71,8 +71,8 @@ where
         return MessageDeserializer::into_event(self)?.deserialize_structured(serializer);
     }
 
-    /// Deserialize the message to a serializer, depending on the message encoding
-    /// You can use this method to transcode this message directly to another serializer, without going through [`Event`]
+    /// Deserialize the message to a serializer, depending on the message encoding.
+    /// You can use this method to transcode this message directly to another serializer, without going through [`Event`].
     fn deserialize_to<R: Sized, T: BinarySerializer<R> + StructuredSerializer<R>>(
         self,
         serializer: T,

src/message/encoding.rs

@@ -1,9 +1,12 @@
 use std::fmt::Debug;
 
-/// Represents one of the possible [message encodings/modes](https://github.com/cloudevents/spec/blob/v1.0/spec.md#message)
+/// Represents one of the possible [message encodings/modes](https://github.com/cloudevents/spec/blob/v1.0/spec.md#message).
 #[derive(PartialEq, Eq, Debug)]
 pub enum Encoding {
+    /// Represents the _structured-mode message_.
     STRUCTURED,
+    /// Represents the _binary-mode message_.
     BINARY,
+    /// Represents a non-CloudEvent or a malformed CloudEvent that cannot be recognized by the SDK.
     UNKNOWN,
 }