From c28ba151515922eabeb1d7d79c8616e0f627fc60 Mon Sep 17 00:00:00 2001
From: Nathy-bajo <bajon7680@gmail.com>
Date: Mon, 23 Dec 2024 12:51:10 +0100
Subject: [PATCH] Clarify and improve #[server] macro docs

---
 packages/server-macro/src/lib.rs | 47 ++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/packages/server-macro/src/lib.rs b/packages/server-macro/src/lib.rs
index 44e07c3116..6fadae1480 100644
--- a/packages/server-macro/src/lib.rs
+++ b/packages/server-macro/src/lib.rs
@@ -64,6 +64,53 @@ use syn::__private::ToTokens;
 /// - `req` and `res`: specify the HTTP request and response types to be used on the server. These
 ///   are typically necessary if you are integrating with a custom server framework (other than Actix/Axum).
 ///   Example: `req = SomeRequestType`, `res = SomeResponseType`.
+/// 
+///
+/// ## Advanced Usage of `input` and `output` Fields
+///
+/// The `input` and `output` fields allow you to customize how arguments and responses are encoded and decoded.
+/// These fields impose specific trait bounds on the types you use. Here are detailed examples for different scenarios:
+///
+/// ### `output = StreamingJson`
+///
+/// Setting the `output` type to `StreamingJson` requires the return type to implement `From<JsonStream<T>>`,
+/// where `T` implements `serde::Serialize` and `serde::de::DeserializeOwned`.
+///
+/// ```rust,ignore
+/// #[server(output = StreamingJson)]
+/// pub async fn json_stream_fn() -> Result<JsonStream<String>, ServerFnError> {
+///     todo!()
+/// }
+/// ```
+///
+/// ### `output = StreamingText`
+///
+/// Setting the `output` type to `StreamingText` requires the return type to implement `From<TextStream>`.
+///
+/// ```rust,ignore
+/// #[server(output = StreamingText)]
+/// pub async fn text_stream_fn() -> Result<TextStream, ServerFnError> {
+///     todo!()
+/// }
+/// ```
+///
+/// ### `output = PostUrl`
+///
+/// Setting the `output` type to `PostUrl` requires the return type to implement `Serialize` and `Deserialize`.
+/// Note that this uses `serde_qs`, which imposes the following constraints:
+/// - The structure must be less than 5 levels deep.
+/// - The structure must not contain any `serde(flatten)` attributes.
+///
+/// ```rust,ignore
+/// #[server(output = PostUrl)]
+/// pub async fn form_fn() -> Result<TextStream, ServerFnError> {
+///     todo!()
+/// }
+/// ```
+///
+/// These examples illustrate how the `output` type impacts the bounds and expectations for your server function. Ensure your return types comply with these requirements.
+/// 
+/// 
 /// ```rust,ignore
 /// #[server(
 ///   name = SomeStructName,