Merge pull request #68 from itowlson/moar-examples-moar-moar-moar

Round out a few more rustdoc examples

Author: itowlson

crates/macro/src/lib.rs

@@ -3,7 +3,27 @@ use quote::quote;
 
 const WIT_PATH: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/wit");
 
-/// Generates the entrypoint to a Spin Redis component written in Rust.
+/// The entrypoint to a Spin Redis component.
+///
+/// The component runs in response to messages on a Redis queue.
+///
+/// # Examples
+///
+/// A handler that logs the content of each message it receives.
+///
+/// ```ignore
+/// # use anyhow::Result;
+/// # use bytes::Bytes;
+/// # use spin_sdk::redis_component;
+/// # use std::str::from_utf8;
+/// #[redis_component]
+/// fn on_message(message: Bytes) -> Result<()> {
+///     println!("{}", from_utf8(&message)?);
+///     Ok(())
+/// }
+/// ```
+///
+/// See <https://spinframework.dev/redis-trigger> for more information.
 #[proc_macro_attribute]
 pub fn redis_component(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let func = syn::parse_macro_input!(item as syn::ItemFn);
@@ -35,7 +55,10 @@ pub fn redis_component(_attr: TokenStream, item: TokenStream) -> TokenStream {
         .into()
 }
 
-/// The entrypoint to a WASI HTTP component written in Rust.
+/// The entrypoint to an HTTP component.
+///
+/// The component runs in response to inbound HTTP requests that match the component's
+/// trigger.
 ///
 /// Functions annotated with this attribute can be of two forms:
 /// * Request/Response
@@ -85,6 +108,8 @@ pub fn redis_component(_attr: TokenStream, item: TokenStream) -> TokenStream {
 ///   // Your logic goes here
 /// }
 /// ```
+///
+/// See <https://spinframework.dev/http-trigger> for more information.
 #[proc_macro_attribute]
 pub fn http_component(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let func = syn::parse_macro_input!(item as syn::ItemFn);

src/http.rs

@@ -1,3 +1,15 @@
+//! Sending and receiving HTTP requests.
+//!
+//! This module includes:
+//!
+//! * Common HTTP types used in sending and receiving.
+//! * The [`send`] function for making HTTP requests.
+//! * The [`Router`] type for routing received HTTP requests.
+//! * The [`conversions`] and [`responses`] modules to make common cases easier.
+//!
+//! For writing a component which handles HTTP requests, see the
+//! [`http_component`](super::http_component) macro.
+
 /// Traits for converting between the various types
 pub mod conversions;
 
@@ -1019,6 +1031,7 @@ impl ResponseOutparam {
 /// # Ok(())
 /// # }
 /// ```
+#[doc(alias = "fetch")]
 pub async fn send<I, O>(request: I) -> Result<O, SendError>
 where
     I: TryIntoOutgoingRequest,

src/http/router.rs

@@ -591,7 +591,32 @@ fn trailing_suffix(req: &Request) -> Option<&str> {
         .and_then(|path_info| path_info.as_str())
 }
 
-/// A macro to help with constructing a Router from a stream of tokens.
+/// A macro to help with constructing a [`Router`] from method-pattern-handler triples.
+///
+/// # Examples
+///
+/// ```no_run
+/// # use spin_sdk::http_router;
+/// # use spin_sdk::http::{IntoResponse, Params, Request, Response, Router};
+/// fn handle_route(req: Request) -> Response {
+///     let router = http_router! {
+///         GET "/user" => list_users,
+///         POST "/user" => create_user,
+///         GET "/user/:id" => get_user,
+///         PUT "/user/:id" => update_user,
+///         DELETE "/user/:id" => delete_user,
+///         _ "/user" => method_not_allowed,
+///         _ "/user/:id" => method_not_allowed
+///     };
+///     router.handle(req)
+/// }
+/// # fn list_users(req: Request, params: Params) -> anyhow::Result<Response> { todo!() }
+/// # fn create_user(req: Request, params: Params) -> anyhow::Result<Response> { todo!() }
+/// # fn get_user(req: Request, params: Params) -> anyhow::Result<Response> { todo!() }
+/// # fn update_user(req: Request, params: Params) -> anyhow::Result<Response> { todo!() }
+/// # fn delete_user(req: Request, params: Params) -> anyhow::Result<Response> { todo!() }
+/// # fn method_not_allowed(req: Request, params: Params) -> anyhow::Result<Response> { todo!() }
+/// ```
 #[macro_export]
 macro_rules! http_router {
     ($($method:tt $path:literal => $h:expr),*) => {

src/lib.rs

@@ -14,7 +14,6 @@ pub mod sqlite;
 /// Large Language Model (Serverless AI) APIs
 pub mod llm;
 
-/// Exports the procedural macros for writing handlers for Spin components.
 pub use spin_macro::*;
 
 #[doc(hidden)]
@@ -54,7 +53,6 @@ extern "C" fn __spin_sdk_language() {}
 #[export_name = concat!("spin-sdk-commit-", env!("SDK_COMMIT"))]
 extern "C" fn __spin_sdk_hash() {}
 
-/// Helpers for building Spin `wasi-http` components.
 pub mod http;
 
 #[allow(missing_docs)]