From fbe7cdc482e26e98471225a453ab45bf12fc8628 Mon Sep 17 00:00:00 2001
From: Greg Johnston <greg.johnston@gmail.com>
Date: Mon, 21 Jul 2025 08:53:38 -0400
Subject: [PATCH] docs: update documentation for `#[lazy]` and `#[lazy_route]`

---
 leptos_macro/src/lib.rs | 35 +++++++++++++++++++++++++++++++----
 router_macro/Cargo.toml |  1 +
 router_macro/src/lib.rs | 31 +++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/leptos_macro/src/lib.rs b/leptos_macro/src/lib.rs
index f7b953254..a9c591103 100644
--- a/leptos_macro/src/lib.rs
+++ b/leptos_macro/src/lib.rs
@@ -1030,14 +1030,41 @@ pub fn memo(input: TokenStream) -> TokenStream {
     memo::memo_impl(input)
 }
 
-/// The `#[lazy]` macro marks an `async` function as a function that can be lazy-loaded from a
-/// separate (WebAssembly) binary.
+/// The `#[lazy]` macro indicates that a function can be lazy-loaded from a separate WebAssembly (WASM) binary.
 ///
 /// The first time the function is called, calling the function will first load that other binary,
-/// then call the function. On subsequent call it will be called immediately, but still return
+/// then call the function. On subsequent calls it will be called immediately, but still return
 /// asynchronously to maintain the same API.
 ///
-/// All parameters and output types should be concrete types, with no generics.
+/// `#[lazy]` can be used to annotate synchronous or `async` functions. In both cases, the final function will be
+/// `async` and must be called as such.
+///
+/// All parameters and output types should be concrete types, with no generics or `impl Trait` types.
+///
+/// This should be used in tandem with a suitable build process, such as `cargo leptos --split`.
+///
+/// ```rust
+/// # use leptos_macro::lazy;
+///
+/// #[lazy]
+/// fn lazy_synchronous_function() -> String {
+///     "Hello, lazy world!".to_string()
+/// }
+///
+/// #[lazy]
+/// async fn lazy_async_function() -> String {
+///     /* do something that requires async work */
+///     "Hello, lazy async world!".to_string()
+/// }
+///
+/// async fn use_lazy_functions() {
+///     // synchronous function has been converted to async
+///     let value1 = lazy_synchronous_function().await;
+///
+///     // async function is still async
+///     let value1 = lazy_async_function().await;
+/// }
+/// ```
 #[proc_macro_attribute]
 #[proc_macro_error]
 pub fn lazy(args: proc_macro::TokenStream, s: TokenStream) -> TokenStream {
diff --git a/router_macro/Cargo.toml b/router_macro/Cargo.toml
index bac9ce42c..fe7f05b53 100644
--- a/router_macro/Cargo.toml
+++ b/router_macro/Cargo.toml
@@ -19,6 +19,7 @@ quote = { workspace = true, default-features = true }
 syn = { features = ["full"], workspace = true, default-features = true }
 
 [dev-dependencies]
+leptos = { path = "../leptos" }
 leptos_router = { path = "../router" }
 leptos_macro = { path = "../leptos_macro" }
 
diff --git a/router_macro/src/lib.rs b/router_macro/src/lib.rs
index 34132f63e..60d60dac3 100644
--- a/router_macro/src/lib.rs
+++ b/router_macro/src/lib.rs
@@ -198,6 +198,37 @@ impl ToTokens for Segments {
 /// add a [`lazy`] annotation to the `view` method, which will cause the code for the view
 /// to lazy-load concurrently with the `data` being loaded for the route.
 ///
+/// ```rust
+/// use leptos::prelude::*;
+/// use leptos_router::{lazy_route, LazyRoute};
+///
+/// // the route definition
+/// #[derive(Debug)]
+/// struct BlogListingRoute {
+///     titles: Resource<Vec<String>>
+/// }
+///
+/// #[lazy_route]
+/// impl LazyRoute for BlogListingRoute {
+///     fn data() -> Self {
+///         Self {
+///             titles: Resource::new(|| (), |_| async {
+///                 vec![/* todo: load blog posts */]
+///             })
+///         }
+///     }
+///
+///     // this function will be lazy-loaded, concurrently with data()
+///     fn view(this: Self) -> AnyView {
+///         let BlogListingRoute { titles } = this;
+///
+///         // ... now you can use the `posts` resource with Suspense, etc.,
+///         // and return AnyView by calling .into_any() on a view
+///         # ().into_any()
+///     }
+/// }
+/// ```
+///
 /// [`impl LazyRoute`]: https://docs.rs/leptos_router/latest/leptos_router/trait.LazyRoute.html
 /// [`lazy`]: https://docs.rs/leptos_macro/latest/leptos_macro/macro.lazy.html
 #[proc_macro_attribute]