Document common items

packages/server/src/adapters/mod.rs

@@ -1,3 +1,15 @@
+//! # Adapters
+//! Adapters for different web frameworks.
+//!
+//! Each adapter provides a set of utilities that is ergonomic to use with the framework.
+//!
+//! Each framework has utilies for some or all of the following:
+//! - Server functions
+//!  - A generic way to register server functions
+//!  - A way to register server functions with a custom handler that allows users to pass in a custom [`DioxusServerContext`] based on the state of the server framework.
+//! - A way to register static WASM files that is accepts [`ServeConfig`]
+//! - A hot reloading web socket that intigrates with [`dioxus-hot-reload`](https://crates.io/crates/dioxus-hot-reload)
+
 #[cfg(feature = "axum")]
 pub mod axum_adapter;
 #[cfg(feature = "salvo")]

packages/server/src/lib.rs

@@ -1,3 +1,66 @@
+//! Fullstack utilities for the [`dioxus`](https://dioxuslabs.com) framework.
+//!
+//! # Features
+//! - Intigrations with the [axum](crate::adapters::axum_adapter), [salvo](crate::adapters::salvo_adapters), and [warp](crate::adapters::warp_adapters) server frameworks with utilities for serving and rendering Dioxus applications.
+//! - Server functions that allow you to call code on the server from the client as if it were a normal function.
+//! - Instant RSX Hot reloading with [`dioxus-hot-reload`](https://crates.io/crates/dioxus-hot-reload).
+//!
+//! # Example
+//! ```rust
+//! #![allow(non_snake_case)]
+//! use dioxus::prelude::*;
+//! use dioxus_server::prelude::*;
+//!
+//! fn main() {
+//!     #[cfg(feature = "web")]
+//!     // Hydrate the application on the client
+//!     dioxus_web::launch_cfg(app, dioxus_web::Config::new().hydrate(true));
+//!     #[cfg(feature = "ssr")]
+//!     {
+//!         GetServerData::register().unwrap();
+//!         tokio::runtime::Runtime::new()
+//!             .unwrap()
+//!             .block_on(async move {
+//!                 let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
+//!                 axum::Server::bind(&addr)
+//!                     .serve(
+//!                         axum::Router::new()
+//!                             // Server side render the application, serve static assets, and register server functions
+//!                             .serve_dioxus_application("", ServeConfigBuilder::new(app, ()))
+//!                             .into_make_service(),
+//!                     )
+//!                     .await
+//!                     .unwrap();
+//!             });
+//!      }
+//! }
+//!
+//! fn app(cx: Scope) -> Element {
+//!     let text = use_state(cx, || "...".to_string());
+//!
+//!     cx.render(rsx! {
+//!         button {
+//!             onclick: move |_| {
+//!                 to_owned![text];
+//!                 async move {
+//!                     if let Ok(data) = get_server_data().await {
+//!                         text.set(data.clone());
+//!                     }
+//!                 }
+//!             },
+//!             "Run a server function"
+//!         }
+//!         "Server said: {text}"
+//!     })
+//! }
+//!
+//! #[server(GetServerData)]
+//! async fn get_server_data() -> Result<String, ServerFnError> {
+//!     Ok("Hello from the server!".to_string())
+//! }
+//! ```
+
+#![warn(missing_docs)]
 #[allow(unused)]
 use dioxus_core::prelude::*;
 
@@ -5,12 +68,13 @@ mod adapters;
 #[cfg(all(debug_assertions, feature = "hot-reload", feature = "ssr"))]
 mod hot_reload;
 #[cfg(feature = "ssr")]
-pub mod render;
+mod render;
 #[cfg(feature = "ssr")]
-mod serve;
+mod serve_config;
 mod server_context;
 mod server_fn;
 
+/// A prelude of commonly used items in dioxus-server.
 pub mod prelude {
     #[cfg(feature = "axum")]
     pub use crate::adapters::axum_adapter::*;
@@ -19,9 +83,7 @@ pub mod prelude {
     #[cfg(feature = "warp")]
     pub use crate::adapters::warp_adapter::*;
     #[cfg(feature = "ssr")]
-    pub use crate::render::*;
-    #[cfg(feature = "ssr")]
-    pub use crate::serve::{ServeConfig, ServeConfigBuilder};
+    pub use crate::serve_config::{ServeConfig, ServeConfigBuilder};
     pub use crate::server_context::DioxusServerContext;
     pub use crate::server_fn::ServerFn;
     #[cfg(feature = "ssr")]

packages/server/src/render.rs

@@ -1,3 +1,5 @@
+//! A shared pool of renderers for efficient server side rendering.
+
 use std::sync::Arc;
 
 use dioxus_core::VirtualDom;
@@ -5,9 +7,10 @@ use dioxus_ssr::Renderer;
 
 use crate::prelude::ServeConfig;
 
+/// State used in server side rendering. This utilizes a pool of [`dioxus_ssr::Renderer`]s to cache static templates between renders.
 #[derive(Clone)]
-pub struct SSRState {
-    // We keep a cache of renderers to avoid re-creating them on every request. They are boxed to make them very cheap to move
+pub(crate) struct SSRState {
+    // We keep a pool of renderers to avoid re-creating them on every request. They are boxed to make them very cheap to move
     renderers: Arc<object_pool::Pool<Renderer>>,
 }
 

packages/server/src/serve.rs → packages/server/src/serve_config.rs

@@ -1,9 +1,12 @@
+//! Configeration for how to serve a Dioxus application
+
 use std::fs::File;
 use std::io::Read;
 use std::path::PathBuf;
 
 use dioxus_core::Component;
 
+/// A ServeConfig is used to configure how to serve a Dioxus application. It contains information about how to serve static assets, and what content to render with [`dioxus-ssr`].
 #[derive(Clone)]
 pub struct ServeConfigBuilder<P: Clone> {
     pub(crate) app: Component<P>,
@@ -14,7 +17,7 @@ pub struct ServeConfigBuilder<P: Clone> {
 }
 
 impl<P: Clone> ServeConfigBuilder<P> {
-    /// Create a new ServeConfig
+    /// Create a new ServeConfigBuilder with the root component and props to render on the server.
     pub fn new(app: Component<P>, props: P) -> Self {
         Self {
             app,
@@ -95,6 +98,8 @@ pub(crate) struct IndexHtml {
     pub(crate) post_main: String,
 }
 
+/// Used to configure how to serve a Dioxus application. It contains information about how to serve static assets, and what content to render with [`dioxus-ssr`].
+/// See [`ServeConfigBuilder`] to create a ServeConfig
 #[derive(Clone)]
 pub struct ServeConfig<P: Clone> {
     pub(crate) app: Component<P>,

packages/server/src/server_context.rs

@@ -4,7 +4,8 @@ use anymap::{any::Any, Map};
 
 type SendSyncAnyMap = Map<dyn Any + Send + Sync + 'static>;
 
-/// A shared context for server functions. This allows you to pass data between your server and the server functions like authentication session data.
+/// A shared context for server functions.
+/// This allows you to pass data between your server framework and the server functions. This can be used to pass request information or information about the state of the server. For example, you could pass authentication data though this context to your server functions.
 #[derive(Clone)]
 pub struct DioxusServerContext {
     shared_context: Arc<RwLock<SendSyncAnyMap>>,
@@ -19,10 +20,12 @@ impl Default for DioxusServerContext {
 }
 
 impl DioxusServerContext {
+    /// Clone a value from the shared server context
     pub fn get<T: Any + Send + Sync + Clone + 'static>(&self) -> Option<T> {
         self.shared_context.read().ok()?.get::<T>().cloned()
     }
 
+    /// Insert a value into the shared server context
     pub fn insert<T: Any + Send + Sync + 'static>(
         &mut self,
         value: T,
@@ -33,3 +36,37 @@ impl DioxusServerContext {
             .map(|_| ())
     }
 }
+
+/// Generate a server context from a tuple of values
+macro_rules! server_context {
+    ($({$(($name:ident: $ty:ident)),*}),*) => {
+        $(
+            #[allow(unused_mut)]
+            impl< $($ty: Send + Sync + 'static),* > From<($($ty,)*)> for $crate::server_context::DioxusServerContext {
+                fn from(( $($name,)* ): ($($ty,)*)) -> Self {
+                    let mut context = $crate::server_context::DioxusServerContext::default();
+                    $(context.insert::<$ty>($name).unwrap();)*
+                    context
+                }
+            }
+        )*
+    };
+}
+
+server_context!(
+    {},
+    {(a: A)},
+    {(a: A), (b: B)},
+    {(a: A), (b: B), (c: C)},
+    {(a: A), (b: B), (c: C), (d: D)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H), (i: I)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H), (i: I), (j: J)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H), (i: I), (j: J), (k: K)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H), (i: I), (j: J), (k: K), (l: L)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H), (i: I), (j: J), (k: K), (l: L), (m: M)},
+    {(a: A), (b: B), (c: C), (d: D), (e: E), (f: F), (g: G), (h: H), (i: I), (j: J), (k: K), (l: L), (m: M), (n: N)}
+);

packages/server/src/server_fn.rs

@@ -1,6 +1,7 @@
 use crate::server_context::DioxusServerContext;
 
 #[cfg(any(feature = "ssr", doc))]
+/// A trait object for a function that be called on serializable arguments and returns a serializable result.
 pub type ServerFnTraitObj = server_fn::ServerFnTraitObj<DioxusServerContext>;
 
 #[cfg(any(feature = "ssr", doc))]
@@ -78,17 +79,14 @@ pub enum ServerRegistrationFnError {
 /// Defines a "server function." A server function can be called from the server or the client,
 /// but the body of its code will only be run on the server, i.e., if a crate feature `ssr` is enabled.
 ///
-/// (This follows the same convention as the Dioxus framework's distinction between `ssr` for server-side rendering,
-/// and `csr` and `hydrate` for client-side rendering and hydration, respectively.)
-///
 /// Server functions are created using the `server` macro.
 ///
 /// The function should be registered by calling `ServerFn::register()`. The set of server functions
-/// can be queried on the server for routing purposes by calling [server_fn_by_path].
+/// can be queried on the server for routing purposes by calling [ServerFunctionRegistry::get].
 ///
-/// Technically, the trait is implemented on a type that describes the server function's arguments.
+/// Technically, the trait is implemented on a type that describes the server function's arguments, not the function itself.
 pub trait ServerFn: server_fn::ServerFn<DioxusServerContext> {
-    /// Registers the server function, allowing the server to query it by URL.
+    /// Registers the server function, allowing the client to query it by URL.
     #[cfg(any(feature = "ssr", doc))]
     fn register() -> Result<(), server_fn::ServerFnError> {
         Self::register_in::<DioxusServerFnRegistry>()