Improved docs in integrations crates (#71)

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>

cloudevents-sdk-actix-web/src/lib.rs

@@ -1,3 +1,46 @@
+//! This crate integrates the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) with [Actix web](https://docs.rs/actix-web/) to easily send and receive CloudEvents.
+//!
+//! To deserialize an HTTP request as CloudEvent:
+//!
+//! ```
+//! use cloudevents_sdk_actix_web::RequestExt;
+//! use actix_web::{HttpRequest, web, post};
+//!
+//! #[post("/")]
+//! async fn post_event(req: HttpRequest, payload: web::Payload) -> Result<String, actix_web::Error> {
+//!     let event = req.into_event(payload).await?;
+//!     println!("Received Event: {:?}", event);
+//!     Ok(format!("{:?}", event))
+//! }
+//! ```
+//!
+//! To serialize a CloudEvent to an HTTP response:
+//!
+//! ```
+//! use cloudevents_sdk_actix_web::HttpResponseBuilderExt;
+//! use actix_web::{HttpRequest, web, get, HttpResponse};
+//! use cloudevents::{EventBuilderV10, EventBuilder};
+//! use serde_json::json;
+//!
+//! #[get("/")]
+//! async fn get_event() -> Result<HttpResponse, actix_web::Error> {
+//!     Ok(HttpResponse::Ok()
+//!         .event(
+//!             EventBuilderV10::new()
+//!                 .id("0001")
+//!                 .ty("example.test")
+//!                 .source("http://localhost/")
+//!                 .data("application/json", json!({"hello": "world"}))
+//!                 .build()
+//!                 .expect("No error while building the event"),
+//!         )
+//!         .await?
+//!     )
+//! }
+//! ```
+//!
+//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`]
+
 #[macro_use]
 mod headers;
 mod server_request;

cloudevents-sdk-actix-web/src/server_request.rs

@@ -12,7 +12,7 @@ use cloudevents::{message, Event};
 use futures::StreamExt;
 use std::convert::TryFrom;
 
-/// Wrapper for [`HttpRequest`] that implements [`MessageDeserializer`] trait
+/// Wrapper for [`HttpRequest`] that implements [`MessageDeserializer`] trait.
 pub struct HttpRequestDeserializer<'a> {
     req: &'a HttpRequest,
     body: Bytes,
@@ -99,7 +99,7 @@ impl<'a> MessageDeserializer for HttpRequestDeserializer<'a> {
     }
 }
 
-/// Method to transform an incoming [`HttpRequest`] to [`Event`]
+/// Method to transform an incoming [`HttpRequest`] to [`Event`].
 pub async fn request_to_event(
     req: &HttpRequest,
     mut payload: web::Payload,
@@ -112,7 +112,7 @@ pub async fn request_to_event(
         .map_err(actix_web::error::ErrorBadRequest)
 }
 
-/// Extention Trait for [`HttpRequest`] which acts as a wrapper for the function [`request_to_event()`]
+/// Extention Trait for [`HttpRequest`] which acts as a wrapper for the function [`request_to_event()`].
 #[async_trait(?Send)]
 pub trait RequestExt {
     async fn into_event(

cloudevents-sdk-actix-web/src/server_response.rs

@@ -10,7 +10,7 @@ use cloudevents::message::{
 use cloudevents::Event;
 use std::str::FromStr;
 
-/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`]
+/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`].
 pub struct HttpResponseSerializer {
     builder: HttpResponseBuilder,
 }
@@ -67,7 +67,7 @@ impl StructuredSerializer<HttpResponse> for HttpResponseSerializer {
     }
 }
 
-/// Method to fill an [`HttpResponseBuilder`] with an [`Event`]
+/// Method to fill an [`HttpResponseBuilder`] with an [`Event`].
 pub async fn event_to_response(
     event: Event,
     response: HttpResponseBuilder,
@@ -76,7 +76,7 @@ pub async fn event_to_response(
         .map_err(actix_web::error::ErrorBadRequest)
 }
 
-/// Extention Trait for [`HttpResponseBuilder`] which acts as a wrapper for the function [`event_to_response()`]
+/// Extention Trait for [`HttpResponseBuilder`] which acts as a wrapper for the function [`event_to_response()`].
 #[async_trait(?Send)]
 pub trait HttpResponseBuilderExt {
     async fn event(

cloudevents-sdk-reqwest/src/client_request.rs

@@ -7,7 +7,7 @@ use cloudevents::Event;
 use reqwest::RequestBuilder;
 use std::str::FromStr;
 
-/// Wrapper for [`RequestBuilder`] that implements [`StructuredSerializer`] & [`BinarySerializer`] traits
+/// Wrapper for [`RequestBuilder`] that implements [`StructuredSerializer`] & [`BinarySerializer`] traits.
 pub struct RequestSerializer {
     req: RequestBuilder,
 }

cloudevents-sdk-reqwest/src/client_response.rs

@@ -11,7 +11,7 @@ use reqwest::header::{HeaderMap, HeaderName};
 use reqwest::Response;
 use std::convert::TryFrom;
 
-/// Wrapper for [`Response`] that implements [`MessageDeserializer`] trait
+/// Wrapper for [`Response`] that implements [`MessageDeserializer`] trait.
 pub struct ResponseDeserializer {
     headers: HeaderMap,
     body: Bytes,
@@ -98,7 +98,7 @@ impl MessageDeserializer for ResponseDeserializer {
     }
 }
 
-/// Method to transform an incoming [`Response`] to [`Event`]
+/// Method to transform an incoming [`Response`] to [`Event`].
 pub async fn response_to_event(res: Response) -> Result<Event> {
     let h = res.headers().to_owned();
     let b = res.bytes().await.map_err(|e| Error::Other {
@@ -108,7 +108,7 @@ pub async fn response_to_event(res: Response) -> Result<Event> {
     MessageDeserializer::into_event(ResponseDeserializer::new(h, b))
 }
 
-/// Extention Trait for [`Response`]which acts as a wrapper for the function [`request_to_event()`]
+/// Extension Trait for [`Response`] which acts as a wrapper for the function [`response_to_event()`].
 #[async_trait(?Send)]
 pub trait ResponseExt {
     async fn into_event(self) -> Result<Event>;

cloudevents-sdk-reqwest/src/lib.rs

@@ -1,3 +1,37 @@
+//! This crate integrates the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) with [reqwest](https://docs.rs/reqwest/) to easily send and receive CloudEvents.
+//!
+//! ```
+//! use cloudevents_sdk_reqwest::{RequestBuilderExt, ResponseExt};
+//! use cloudevents::{EventBuilderV10, EventBuilder};
+//! use serde_json::json;
+//!
+//! # async fn example() {
+//! let client = reqwest::Client::new();
+//!
+//! // Prepare the event to send
+//! let event_to_send = EventBuilderV10::new()
+//!     .id("0001")
+//!     .ty("example.test")
+//!     .source("http://localhost/")
+//!     .data("application/json", json!({"hello": "world"}))
+//!     .build()
+//!     .expect("No error while building the event");
+//!
+//! // Send request
+//! let response = client.post("http://localhost")
+//!   .event(event_to_send)
+//!   .expect("Error while serializing the event")
+//!   .send().await
+//!   .expect("Error while sending the request");
+//! // Parse response as event
+//! let received_event = response
+//!   .into_event().await
+//!   .expect("Error while deserializing the response");
+//! # }
+//! ```
+//!
+//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`]
+
 #[macro_use]
 mod headers;
 mod client_request;

example-projects/actix-web-example/src/main.rs

@@ -2,8 +2,6 @@ use actix_web::{get, post, web, App, HttpRequest, HttpResponse, HttpServer};
 use cloudevents::{EventBuilder, EventBuilderV10};
 use cloudevents_sdk_actix_web::{HttpResponseBuilderExt, RequestExt};
 use serde_json::json;
-use std::str::FromStr;
-use url::Url;
 
 #[post("/")]
 async fn post_event(req: HttpRequest, payload: web::Payload) -> Result<String, actix_web::Error> {
@@ -21,7 +19,7 @@ async fn get_event() -> Result<HttpResponse, actix_web::Error> {
             EventBuilderV10::new()
                 .id("0001")
                 .ty("example.test")
-                .source(Url::from_str("http://localhost/").unwrap())
+                .source("http://localhost/")
                 .data("application/json", payload)
                 .extension("someint", "10")
                 .build()

src/lib.rs

@@ -19,8 +19,8 @@
 //!
 //! If you're looking for Protocol Binding implementations, look at crates:
 //!
-//! * `cloudevents-sdk-actix-web`: Integration with [Actix Web](https://github.com/actix/actix-web)
+//! * [cloudevents-sdk-actix-web](https://docs.rs/cloudevents-sdk-actix-web): Integration with [Actix Web](https://github.com/actix/actix-web)
-//! * `cloudevents-sdk-reqwest`: Integration with [reqwest](https://github.com/seanmonstar/reqwest)
+//! * [cloudevents-sdk-reqwest](https://docs.rs/cloudevents-sdk-reqwest): Integration with [reqwest](https://github.com/seanmonstar/reqwest)
 //!
 
 extern crate serde;