Add examples to rustdoc

Signed-off-by: itowlson <[email protected]>

Author: itowlson

.github/workflows/build.yml

@@ -39,3 +39,6 @@ jobs:
         shell: bash
         run: cargo test --workspace
 
+      - name: Validate docs examples
+        shell: bash
+        run: cargo test --doc

src/http.rs

@@ -613,6 +613,59 @@ impl ResponseOutparam {
 }
 
 /// Send an outgoing request
+///
+/// # Examples
+///
+/// Get the example.com home page:
+///
+/// ```no_run
+/// use spin_sdk::http::{Request, Response};
+///
+/// # #[tokio::main]
+/// # async fn main() -> anyhow::Result<()> {
+/// let request = Request::get("example.com").build();
+/// let response: Response = spin_sdk::http::send(request).await?;
+/// println!("{}", response.body().len());
+/// # Ok(())
+/// # }
+/// ```
+///
+/// Use the `http` crate Request type to send a data transfer value:
+///
+/// ```no_run
+/// use hyperium::Request;
+///
+/// #[derive(serde::Serialize)]
+/// struct User {
+///     name: String,
+/// }
+///
+/// impl spin_sdk::http::conversions::TryIntoBody for User {
+///     type Error = serde_json::Error;
+///
+///     fn try_into_body(self) -> Result<Vec<u8>, Self::Error> {
+///         serde_json::to_vec(&self)
+///     }
+/// }
+///
+/// # #[tokio::main]
+/// # async fn main() -> anyhow::Result<()> {
+/// let user = User {
+///     name: "Alice".to_owned(),
+/// };
+///
+/// let request = hyperium::Request::builder()
+///     .method("POST")
+///     .uri("https://example.com/users")
+///     .header("content-type", "application/json")
+///     .body(user)?;
+///
+/// let response: hyperium::Response<()> = spin_sdk::http::send(request).await?;
+///
+/// println!("{}", response.status().is_success());
+/// # Ok(())
+/// # }
+/// ```
 pub async fn send<I, O>(request: I) -> Result<O, SendError>
 where
     I: TryIntoOutgoingRequest,

src/key_value.rs

@@ -3,14 +3,73 @@
 //! This module provides a generic interface for key-value storage, which may be implemented by the host various
 //! ways (e.g. via an in-memory table, a local file, or a remote database). Details such as consistency model and
 //! durability will depend on the implementation and may vary from one to store to the next.
+//!
+//! # Examples
+//!
+//! Open the default store and set the 'message' key:
+//!
+//! ```no_run
+//! # fn main() -> anyhow::Result<()> {
+//! let store = spin_sdk::key_value::Store::open_default()?;
+//! store.set("message", "Hello world".as_bytes())?;
+//! # Ok(())
+//! # }
+//! ```
 
 use super::wit::v2::key_value;
 
 #[cfg(feature = "json")]
 use serde::{de::DeserializeOwned, Serialize};
 
 #[doc(inline)]
-pub use key_value::{Error, Store};
+pub use key_value::Error;
+
+/// An open key-value store.
+///
+/// # Examples
+///
+/// Open the default store and set the 'message' key:
+///
+/// ```no_run
+/// # fn main() -> anyhow::Result<()> {
+/// let store = spin_sdk::key_value::Store::open_default()?;
+/// store.set("message", "Hello world".as_bytes())?;
+/// # Ok(())
+/// # }
+/// ```
+///
+/// Open the default store and get the 'message' key:
+///
+/// ```no_run
+/// # fn main() -> anyhow::Result<()> {
+/// let store = spin_sdk::key_value::Store::open_default()?;
+/// let message = store.gettt("message")?;
+/// let response = message.unwrap_or_else(|| "not found".into());
+/// # Ok(())
+/// # }
+/// ```
+///
+/// Open a named store and list all the keys defined in it:
+///
+/// ```no_run
+/// # fn main() -> anyhow::Result<()> {
+/// let store = spin_sdk::key_value::Store::open("finance")?;
+/// let keys = store.get_keys()?;
+/// # Ok(())
+/// # }
+/// ```
+///
+/// Open the default store and delete the 'message' key:
+///
+/// ```no_run
+/// # fn main() -> anyhow::Result<()> {
+/// let store = spin_sdk::key_value::Store::open_default()?;
+/// store.delete("message")?;
+/// # Ok(())
+/// # }
+/// ```
+#[doc(inline)]
+pub use key_value::Store;
 
 impl Store {
     /// Open the default store.
@@ -24,6 +83,31 @@ impl Store {
 impl Store {
     #[cfg(feature = "json")]
     /// Serialize the given data to JSON, then set it as the value for the specified `key`.
+    ///
+    /// # Examples
+    ///
+    /// Open the default store and save a customer information document against the customer ID:
+    ///
+    /// ```no_run
+    /// # use serde::{Deserialize, Serialize};
+    /// #[derive(Deserialize, Serialize)]
+    /// struct Customer {
+    ///     name: String,
+    ///     address: Vec<String>,
+    /// }
+    ///
+    /// # fn main() -> anyhow::Result<()> {
+    /// let customer_id = "CR1234567";
+    /// let customer = Customer {
+    ///     name: "Alice".to_owned(),
+    ///     address: vec!["Wonderland Way".to_owned()],
+    /// };
+    ///
+    /// let store = spin_sdk::key_value::Store::open_default()?;
+    /// store.set_json(customer_id, &customer)?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn set_json<T: Serialize>(
         &self,
         key: impl AsRef<str>,
@@ -34,6 +118,27 @@ impl Store {
 
     #[cfg(feature = "json")]
     /// Deserialize an instance of type `T` from the value of `key`.
+    ///
+    /// # Examples
+    ///
+    /// Open the default store and retrieve a customer information document by customer ID:
+    ///
+    /// ```no_run
+    /// # use serde::{Deserialize, Serialize};
+    /// #[derive(Deserialize, Serialize)]
+    /// struct Customer {
+    ///     name: String,
+    ///     address: Vec<String>,
+    /// }
+    ///
+    /// # fn main() -> anyhow::Result<()> {
+    /// let customer_id = "CR1234567";
+    ///
+    /// let store = spin_sdk::key_value::Store::open_default()?;
+    /// let customer = store.get_json::<Customer>(customer_id)?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn get_json<T: DeserializeOwned>(
         &self,
         key: impl AsRef<str>,