From 6133a6e67fa3f2d4879a1b089962d9a0318bb08d Mon Sep 17 00:00:00 2001
From: slinkydeveloper <francescoguard@gmail.com>
Date: Thu, 29 Oct 2020 19:14:07 +0100
Subject: [PATCH] Docs in cloudevents-sdk-reqwest

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>
---
 cloudevents-sdk-reqwest/Cargo.toml            |  1 +
 cloudevents-sdk-reqwest/src/client_request.rs | 15 ++++++++++++---
 .../src/client_response.rs                    | 11 ++++++++++-
 cloudevents-sdk-reqwest/src/lib.rs            | 19 +++++++++----------
 4 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/cloudevents-sdk-reqwest/Cargo.toml b/cloudevents-sdk-reqwest/Cargo.toml
index 50a0fa3..b0ecf5e 100644
--- a/cloudevents-sdk-reqwest/Cargo.toml
+++ b/cloudevents-sdk-reqwest/Cargo.toml
@@ -8,6 +8,7 @@ description = "CloudEvents official Rust SDK - Reqwest integration"
 documentation = "https://docs.rs/cloudevents-sdk-reqwest"
 repository = "https://github.com/cloudevents/sdk-rust"
 readme = "README.md"
+categories = ["web-programming", "encoding", "web-programming::http-client"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
diff --git a/cloudevents-sdk-reqwest/src/client_request.rs b/cloudevents-sdk-reqwest/src/client_request.rs
index 1e5d395..edd837a 100644
--- a/cloudevents-sdk-reqwest/src/client_request.rs
+++ b/cloudevents-sdk-reqwest/src/client_request.rs
@@ -62,13 +62,16 @@ impl StructuredSerializer<RequestBuilder> for RequestSerializer {
     }
 }
 
-/// Method to fill a [`RequestBuilder`] with an [`Event`]
+/// Method to fill a [`RequestBuilder`] with an [`Event`].
 pub fn event_to_request(event: Event, request_builder: RequestBuilder) -> Result<RequestBuilder> {
     BinaryDeserializer::deserialize_binary(event, RequestSerializer::new(request_builder))
 }
 
-/// Extention Trait for [`RequestBuilder`] which acts as a wrapper for the function [`event_to_request()`]
-pub trait RequestBuilderExt {
+/// Extension Trait for [`RequestBuilder`] which acts as a wrapper for the function [`event_to_request()`].
+///
+/// This trait is sealed and cannot be implemented for types outside of this crate.
+pub trait RequestBuilderExt: private::Sealed {
+    /// Write in this [`RequestBuilder`] the provided [`Event`]. Similar to invoking [`Event`].
     fn event(self, event: Event) -> Result<RequestBuilder>;
 }
 
@@ -78,6 +81,12 @@ impl RequestBuilderExt for RequestBuilder {
     }
 }
 
+// Sealing the RequestBuilderExt
+mod private {
+    pub trait Sealed {}
+    impl Sealed for reqwest::RequestBuilder {}
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/cloudevents-sdk-reqwest/src/client_response.rs b/cloudevents-sdk-reqwest/src/client_response.rs
index 10bb582..fc7d1a7 100644
--- a/cloudevents-sdk-reqwest/src/client_response.rs
+++ b/cloudevents-sdk-reqwest/src/client_response.rs
@@ -109,8 +109,11 @@ pub async fn response_to_event(res: Response) -> Result<Event> {
 }
 
 /// Extension Trait for [`Response`] which acts as a wrapper for the function [`response_to_event()`].
+///
+/// This trait is sealed and cannot be implemented for types outside of this crate.
 #[async_trait(?Send)]
-pub trait ResponseExt {
+pub trait ResponseExt: private::Sealed {
+    /// Convert this [`Response`] to [`Event`].
     async fn into_event(self) -> Result<Event>;
 }
 
@@ -121,6 +124,12 @@ impl ResponseExt for Response {
     }
 }
 
+// Sealing the ResponseExt
+mod private {
+    pub trait Sealed {}
+    impl Sealed for reqwest::Response {}
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/cloudevents-sdk-reqwest/src/lib.rs b/cloudevents-sdk-reqwest/src/lib.rs
index 73e98be..a8b1f31 100644
--- a/cloudevents-sdk-reqwest/src/lib.rs
+++ b/cloudevents-sdk-reqwest/src/lib.rs
@@ -5,7 +5,7 @@
 //! use cloudevents::{EventBuilderV10, EventBuilder};
 //! use serde_json::json;
 //!
-//! # async fn example() {
+//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
 //! let client = reqwest::Client::new();
 //!
 //! // Prepare the event to send
@@ -14,23 +14,22 @@
 //!     .ty("example.test")
 //!     .source("http://localhost/")
 //!     .data("application/json", json!({"hello": "world"}))
-//!     .build()
-//!     .expect("No error while building the event");
+//!     .build()?;
 //!
 //! // 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");
+//!   .event(event_to_send)?
+//!   .send().await?;
 //! // Parse response as event
 //! let received_event = response
-//!   .into_event().await
-//!   .expect("Error while deserializing the response");
+//!   .into_event().await?;
+//! # Ok(())
 //! # }
 //! ```
 //!
-//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`]
+//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`].
+
+#![deny(broken_intra_doc_links)]
 
 #[macro_use]
 mod headers;