From 1aae5807a24134b3f0a181e09e143b42fff98851 Mon Sep 17 00:00:00 2001 From: itowlson Date: Tue, 11 Feb 2025 13:19:29 +1300 Subject: [PATCH] Add examples to rustdoc Signed-off-by: itowlson --- .github/workflows/build.yml | 3 + src/http.rs | 53 ++++++++++++++++++ src/key_value.rs | 107 +++++++++++++++++++++++++++++++++++- 3 files changed, 162 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 8ccccaa..bb65622 100644 --- a/.github/workflows/build.yml +++ b/.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 diff --git a/src/http.rs b/src/http.rs index abd2fc0..d281227 100644 --- a/src/http.rs +++ b/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, 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(request: I) -> Result where I: TryIntoOutgoingRequest, diff --git a/src/key_value.rs b/src/key_value.rs index 7a62a8f..32b646b 100644 --- a/src/key_value.rs +++ b/src/key_value.rs @@ -3,6 +3,18 @@ //! 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; @@ -10,7 +22,54 @@ use super::wit::v2::key_value; 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, + /// } + /// + /// # 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( &self, key: impl AsRef, @@ -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, + /// } + /// + /// # fn main() -> anyhow::Result<()> { + /// let customer_id = "CR1234567"; + /// + /// let store = spin_sdk::key_value::Store::open_default()?; + /// let customer = store.get_json::(customer_id)?; + /// # Ok(()) + /// # } + /// ``` pub fn get_json( &self, key: impl AsRef,