Skip to content

Commit

Permalink
chore(server_fn): improve docs in server_fn (#1734)
Browse files Browse the repository at this point in the history
  • Loading branch information
fundon authored Sep 20, 2023
1 parent fafb6c0 commit 2374439
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 8 deletions.
4 changes: 3 additions & 1 deletion server_fn/src/default.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ inventory::collect!(DefaultServerFnTraitObj);

/// Attempts to find a server function registered at the given path.
///
/// This can be used by a server to handle the requests, as in the following example (using `actix-web`)
/// This can be used by a server to handle the requests, as in the following example (using [`actix-web`]).
///
/// ```rust, ignore
/// #[post("{tail:.*}")]
Expand Down Expand Up @@ -64,6 +64,8 @@ inventory::collect!(DefaultServerFnTraitObj);
/// }
/// }
/// ```
///
/// [`actix-web`]: <https://docs.rs/actix-web/>
#[cfg(any(feature = "ssr", doc))]
pub fn server_fn_by_path(
path: &str,
Expand Down
19 changes: 12 additions & 7 deletions server_fn/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
//!
//! ### `#[server]`
//!
//! The [`#[server]`](https://docs.rs/server_fn/latest/server_fn/attr.server.html) macro allows you to annotate a function to
//! The [`#[server]`][server] macro allows you to annotate a function to
//! indicate that it should only run on the server (i.e., when you have an `ssr` feature in your
//! crate that is enabled).
//!
Expand Down Expand Up @@ -69,12 +69,15 @@
//! - **Server functions must return `Result<T, ServerFnError>`.** Even if the work being done
//! inside the function body can’t fail, the processes of serialization/deserialization and the
//! network call are fallible.
//! - **Return types must implement [Serialize](serde::Serialize).**
//! - **Return types must implement [`serde::Serialize`].**
//! This should be fairly obvious: we have to serialize arguments to send them to the server, and we
//! need to deserialize the result to return it to the client.
//! - **Arguments must be implement [serde::Serialize].** They are serialized as an `application/x-www-form-urlencoded`
//! form data using [`serde_qs`](https://docs.rs/serde_qs/latest/serde_qs/) or as `application/cbor`
//! using [`cbor`](https://docs.rs/cbor/latest/cbor/).
//! - **Arguments must be implement [`serde::Serialize`].** They are serialized as an `application/x-www-form-urlencoded`
//! form data using [`serde_qs`] or as `application/cbor` using [`cbor`].
//!
//! [server]: <https://docs.rs/server_fn/latest/server_fn/attr.server.html>
//! [`serde_qs`]: <https://docs.rs/serde_qs/latest/serde_qs/>
//! [`cbor`]: <https://docs.rs/cbor/latest/cbor/>
// used by the macro
#[doc(hidden)]
Expand Down Expand Up @@ -202,7 +205,7 @@ pub enum Payload {

/// Attempts to find a server function registered at the given path.
///
/// This can be used by a server to handle the requests, as in the following example (using `actix-web`)
/// This can be used by a server to handle the requests, as in the following example (using [`actix-web`])
///
/// ```rust, ignore
/// #[post("{tail:.*}")]
Expand Down Expand Up @@ -243,6 +246,8 @@ pub enum Payload {
/// }
/// }
/// ```
///
/// [`actix-web`]: <https://docs.rs/actix-web/>
#[cfg(any(feature = "ssr", doc))]
pub fn server_fn_by_path<T: 'static, R: ServerFunctionRegistry<T>>(
path: &str,
Expand Down Expand Up @@ -323,7 +328,7 @@ impl quote::ToTokens for Encoding {
///
/// Server functions are created using the `server` macro.
///
/// The set of server functions can be queried on the server for routing purposes by calling [server_fn_by_path].
/// The set of server functions can be queried on the server for routing purposes by calling [`server_fn_by_path`].
///
/// Technically, the trait is implemented on a type that describes the server function's arguments.
pub trait ServerFn<T: 'static>
Expand Down

0 comments on commit 2374439

Please sign in to comment.