clean up docs (closes #2197)

server_fn/Cargo.toml

@@ -102,3 +102,6 @@ default-tls = ["reqwest?/default-tls"]
 rustls = ["reqwest?/rustls-tls"]
 reqwest = ["dep:reqwest"]
 ssr = ["inventory"]
+
+[package.metadata.docs.rs]
+all-features = true

server_fn/src/client.rs

@@ -33,7 +33,7 @@ pub trait Client<CustErr> {
     ) -> impl Future<Output = Result<Self::Response, ServerFnError<CustErr>>> + Send;
 }
 
-#[cfg(any(feature = "browser", doc))]
+#[cfg(feature = "browser")]
 /// Implements [`Client`] for a `fetch` request in the browser.
 pub mod browser {
     use super::Client;
@@ -67,7 +67,7 @@ pub mod browser {
     }
 }
 
-#[cfg(any(feature = "reqwest", doc))]
+#[cfg(feature = "reqwest")]
 /// Implements [`Client`] for a request made by [`reqwest`].
 pub mod reqwest {
     use super::Client;

server_fn/src/codec/mod.rs

@@ -11,37 +11,37 @@
 //! Rather than a limited number of encodings, this crate allows you to define server functions that
 //! mix and match the input encoding and output encoding. To define a new encoding, you simply implement
 //! an input combination ([`IntoReq`] and [`FromReq`]) and/or an output encoding ([`IntoRes`] and [`FromRes`]).
-//! This genuinely is an and/or: while some encodings can be used for both input and output ([`Json`], [`Cbor`], [`Rkyv`]),
-//! others can only be used for input ([`GetUrl`], [`MultipartData`]) or only output ([`ByteStream`], [`StreamingText`]).
+//! This genuinely is an and/or: while some encodings can be used for both input and output (`Json`, `Cbor`, `Rkyv`),
+//! others can only be used for input (`GetUrl`, `MultipartData`).
 
 #[cfg(feature = "cbor")]
 mod cbor;
-#[cfg(any(feature = "cbor", doc))]
+#[cfg(feature = "cbor")]
 pub use cbor::*;
 
 #[cfg(feature = "json")]
 mod json;
-#[cfg(any(feature = "json", doc))]
+#[cfg(feature = "json")]
 pub use json::*;
 
 #[cfg(feature = "serde-lite")]
 mod serde_lite;
-#[cfg(any(feature = "serde-lite", doc))]
+#[cfg(feature = "serde-lite")]
 pub use serde_lite::*;
 
 #[cfg(feature = "rkyv")]
 mod rkyv;
-#[cfg(any(feature = "rkyv", doc))]
+#[cfg(feature = "rkyv")]
 pub use rkyv::*;
 
 #[cfg(feature = "url")]
 mod url;
-#[cfg(any(feature = "url", doc))]
+#[cfg(feature = "url")]
 pub use url::*;
 
 #[cfg(feature = "multipart")]
 mod multipart;
-#[cfg(any(feature = "multipart", doc))]
+#[cfg(feature = "multipart")]
 pub use multipart::*;
 
 mod stream;
@@ -52,7 +52,7 @@ pub use stream::*;
 
 /// Serializes a data type into an HTTP request, on the client.
 ///
-/// Implementations use the methods of the [`ClientReq`](crate::ClientReq) trait to
+/// Implementations use the methods of the [`ClientReq`](crate::request::ClientReq) trait to
 /// convert data into a request body. They are often quite short, usually consisting
 /// of just two steps:
 /// 1. Serializing the data into some [`String`], [`Bytes`](bytes::Bytes), or [`Stream`](futures::Stream).

server_fn/src/codec/stream.rs

@@ -114,16 +114,26 @@ where
 /// An encoding that represents a stream of text.
 ///
 /// A server function that uses this as its output encoding should return [`TextStream`].
+///
+/// **Note**: Browser fetch requests do not currently support full request duplexing, which
+/// means that that they do begin handling responses until the full request has been sent.
+/// This means that if you use streaming text as an input encoding, the input stream needs to
+/// end before the output will begin.
 pub struct StreamingText;
 
 impl Encoding for StreamingText {
     const CONTENT_TYPE: &'static str = "text/plain";
     const METHOD: Method = Method::POST;
 }
 
-/// A stream of bytes.
+/// A stream of text.
 ///
 /// A server function can return this type if its output encoding is [`StreamingText`].
+///
+/// **Note**: Browser fetch requests do not currently support full request duplexing, which
+/// means that that they do begin handling responses until the full request has been sent.
+/// This means that if you use streaming text as an input encoding, the input stream needs to
+/// end before the output will begin.
 pub struct TextStream<CustErr = NoCustomError>(
     Pin<Box<dyn Stream<Item = Result<String, ServerFnError<CustErr>>> + Send>>,
 );

server_fn/src/error.rs

@@ -79,14 +79,13 @@ impl FromStr for NoCustomError {
     }
 }
 
-/// Wraps some error type, which may implement any of [`Error`], [`Clone`], or
+/// Wraps some error type, which may implement any of [`Error`](trait@std::error::Error), [`Clone`], or
 /// [`Display`].
 #[derive(Debug)]
 pub struct WrapError<T>(pub T);
 
-/// This helper macro lets you call the gnarly autoref-specialization call
-/// without having to worry about things like how many & you need.
-/// Mostly used when you impl From<ServerFnError> for YourError
+/// A helper macro to convert a variety of different types into `ServerFnError`.
+/// This should mostly be used if you are implementing `From<ServerFnError>` for `YourError`.
 #[macro_export]
 macro_rules! server_fn_error {
     () => {{
@@ -161,7 +160,7 @@ impl<E> ViaError<E> for WrapError<E> {
 
 /// Type for errors that can occur when using server functions.
 ///
-/// Unlike [`ServerFnErrorErr`], this does not implement [`Error`](std::error::Error).
+/// Unlike [`ServerFnErrorErr`], this does not implement [`Error`](trait@std::error::Error).
 /// This means that other error types can easily be converted into it using the
 /// `?` operator.
 #[derive(Debug, Clone, Serialize, Deserialize)]

server_fn/src/lib.rs

@@ -32,7 +32,8 @@
 //! indicate that it should only run on the server (i.e., when you have an `ssr` feature in your
 //! crate that is enabled).
 //!
-//! **Important**: Before calling a server function on a non-web platform, you must set the server URL by calling [`set_server_url`].
+//! **Important**: Before calling a server function on a non-web platform, you must set the server URL by calling
+//! [`set_server_url`](crate::client::set_server_url).
 //!
 //! ```rust,ignore
 //! #[server]
@@ -148,7 +149,7 @@ pub use xxhash_rust;
 /// Defines a function that runs only on the server, but can be called from the server or the client.
 ///
 /// The type for which `ServerFn` is implemented is actually the type of the arguments to the function,
-/// while the function body itself is implemented in [`run_body`].
+/// while the function body itself is implemented in [`run_body`](ServerFn::run_body).
 ///
 /// This means that `Self` here is usually a struct, in which each field is an argument to the function.
 /// In other words,

server_fn/src/request/mod.rs

@@ -4,16 +4,16 @@ use futures::Stream;
 use std::{borrow::Cow, future::Future};
 
 /// Request types for Actix.
-#[cfg(any(feature = "actix", doc))]
+#[cfg(feature = "actix")]
 pub mod actix;
 /// Request types for Axum.
-#[cfg(any(feature = "axum", doc))]
+#[cfg(feature = "axum")]
 pub mod axum;
 /// Request types for the browser.
-#[cfg(any(feature = "browser", doc))]
+#[cfg(feature = "browser")]
 pub mod browser;
 /// Request types for [`reqwest`].
-#[cfg(any(feature = "reqwest", doc))]
+#[cfg(feature = "reqwest")]
 pub mod reqwest;
 
 /// Represents a request as made by the client.

server_fn/src/response/mod.rs

@@ -1,14 +1,14 @@
 /// Response types for Actix.
-#[cfg(any(feature = "actix", doc))]
+#[cfg(feature = "actix")]
 pub mod actix;
 /// Response types for the browser.
-#[cfg(any(feature = "browser", doc))]
+#[cfg(feature = "browser")]
 pub mod browser;
 /// Response types for Axum.
-#[cfg(any(feature = "axum", doc))]
+#[cfg(feature = "axum")]
 pub mod http;
 /// Response types for [`reqwest`].
-#[cfg(any(feature = "reqwest", doc))]
+#[cfg(feature = "reqwest")]
 pub mod reqwest;
 
 use crate::error::ServerFnError;