chore(leptos_router): improve docs (#1769)

router/src/components/form.rs

@@ -23,8 +23,8 @@ pub fn Form<A>(
     #[prop(optional)]
     method: Option<&'static str>,
     /// [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-action)
-    /// is the URL that processes the form submission. Takes a [String], [&str], or a reactive
-    /// function that returns a [String].
+    /// is the URL that processes the form submission. Takes a [`String`], [`&str`], or a reactive
+    /// function that returns a [`String`].
     action: A,
     /// [`enctype`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-enctype)
     /// is the MIME type of the form submission if `method` is `post`.
@@ -37,13 +37,13 @@ pub fn Form<A>(
     /// A signal that will be set if the form submission ends in an error.
     #[prop(optional)]
     error: Option<RwSignal<Option<Box<dyn Error>>>>,
-    /// A callback will be called with the [FormData](web_sys::FormData) when the form is submitted.
+    /// A callback will be called with the [`FormData`](web_sys::FormData) when the form is submitted.
     #[prop(optional)]
     on_form_data: Option<OnFormData>,
     /// Sets the `class` attribute on the underlying `<form>` tag, making it easier to style.
     #[prop(optional, into)]
     class: Option<AttributeValue>,
-    /// A callback will be called with the [Response](web_sys::Response) the server sends in response
+    /// A callback will be called with the [`Response`](web_sys::Response) the server sends in response
     /// to a form submission.
     #[prop(optional)]
     on_response: Option<OnResponse>,

router/src/components/link.rs

@@ -3,7 +3,7 @@ use leptos::{leptos_dom::IntoView, *};
 use std::borrow::Cow;
 
 /// Describes a value that is either a static or a reactive URL, i.e.,
-/// a [String], a [&str], or a reactive `Fn() -> String`.
+/// a [`String`], a [`&str`], or a reactive `Fn() -> String`.
 pub trait ToHref {
     /// Converts the (static or reactive) URL into a function that can be called to
     /// return the URL.

router/src/components/redirect.rs

@@ -11,9 +11,13 @@ use std::rc::Rc;
 /// an absolute path, prefix it with `/`).
 ///
 /// **Note**: Support for server-side redirects is provided by the server framework
-/// integrations (`leptos_actix`, `leptos_axum`, and `leptos_viz`). If you’re not using one of those
+/// integrations ([`leptos_actix`], [`leptos_axum`], and [`leptos_viz`]). If you’re not using one of those
 /// integrations, you should manually provide a way of redirecting on the server
-/// using [provide_server_redirect].
+/// using [`provide_server_redirect`].
+///
+/// [`leptos_actix`]: <https://docs.rs/leptos_actix/>
+/// [`leptos_axum`]: <https://docs.rs/leptos_axum/>
+/// [`leptos_viz`]: <https://docs.rs/leptos_viz/>
 #[cfg_attr(
     any(debug_assertions, feature = "ssr"),
     tracing::instrument(level = "trace", skip_all,)
@@ -57,8 +61,8 @@ where
 }
 
 /// Wrapping type for a function provided as context to allow for
-/// server-side redirects. See [provide_server_redirect]
-/// and [Redirect].
+/// server-side redirects. See [`provide_server_redirect`]
+/// and [`Redirect`].
 #[derive(Clone)]
 pub struct ServerRedirectFunction {
     f: Rc<dyn Fn(&str)>,

router/src/components/route.rs

@@ -49,7 +49,7 @@ pub fn Route<E, F, P>(
     /// wildcard (`user/*any`).
     path: P,
     /// The view that should be shown when this route is matched. This can be any function
-    /// that returns a type that implements [IntoView] (like `|| view! { <p>"Show this"</p> })`
+    /// that returns a type that implements [`IntoView`] (like `|| view! { <p>"Show this"</p> })`
     /// or `|| view! { <MyComponent/>` } or even, for a component with no props, `MyComponent`).
     view: F,
     /// The mode that this route prefers during server-side rendering. Defaults to out-of-order streaming.
@@ -250,7 +250,7 @@ impl RouteContext {
     /// including param values in their places.
     ///
     /// e.g., this will return `/article/0` rather than `/article/:id`.
-    /// For the opposite behavior, see [RouteContext::original_path].
+    /// For the opposite behavior, see [`RouteContext::original_path`].
     #[track_caller]
     pub fn path(&self) -> String {
         #[cfg(debug_assertions)]
@@ -273,7 +273,7 @@ impl RouteContext {
     /// with the param name rather than the matched parameter itself.
     ///
     /// e.g., this will return `/article/:id` rather than `/article/0`
-    /// For the opposite behavior, see [RouteContext::path].
+    /// For the opposite behavior, see [`RouteContext::path`].
     pub fn original_path(&self) -> &str {
         &self.inner.original_path
     }

router/src/components/router.rs

@@ -27,8 +27,8 @@ pub fn Router(
     #[prop(optional, into)]
     set_is_routing: Option<SignalSetter<bool>>,
     /// The `<Router/>` should usually wrap your whole page. It can contain
-    /// any elements, and should include a [Routes](crate::Routes) component somewhere
-    /// to define and display [Route](crate::Route)s.
+    /// any elements, and should include a [`Routes`](crate::Routes) component somewhere
+    /// to define and display [`Route`](crate::Route)s.
     children: Children,
 ) -> impl IntoView {
     // create a new RouterContext and provide it to every component beneath the router
@@ -198,7 +198,7 @@ impl RouterContext {
         self.inner.location.pathname
     }
 
-    /// The [RouteContext] of the base route.
+    /// The [`RouteContext`] of the base route.
     pub fn base(&self) -> RouteContext {
         self.inner.base.clone()
     }

router/src/extract_routes.rs

@@ -47,8 +47,12 @@ impl RouteListing {
 }
 
 /// Generates a list of all routes this application could possibly serve. This returns the raw routes in the leptos_router
-/// format. Odds are you want `generate_route_list()` from either the actix, axum, or viz integrations if you want
-/// to work with their router
+/// format. Odds are you want `generate_route_list()` from either the [`actix`], [`axum`], or [`viz`] integrations if you want
+/// to work with their router.
+///
+/// [`actix`]: <https://docs.rs/actix/>
+/// [`axum`]: <https://docs.rs/axum/>
+/// [`viz`]: <https://docs.rs/viz/>
 pub fn generate_route_list_inner<IV>(
     app_fn: impl FnOnce() -> IV + 'static,
 ) -> Vec<RouteListing>

router/src/history/mod.rs

@@ -18,8 +18,8 @@ impl std::fmt::Debug for RouterIntegrationContext {
     }
 }
 
-/// The [Router](crate::Router) relies on a [RouterIntegrationContext], which tells the router
-/// how to find things like the current URL, and how to navigate to a new page. The [History] trait
+/// The [`Router`](crate::Router) relies on a [`RouterIntegrationContext`], which tells the router
+/// how to find things like the current URL, and how to navigate to a new page. The [`History`] trait
 /// can be implemented on any type to provide this information.
 pub trait History {
     /// A signal that updates whenever the current location changes.
@@ -139,7 +139,7 @@ impl History for BrowserIntegration {
     }
 }
 
-/// The wrapper type that the [Router](crate::Router) uses to interact with a [History].
+/// The wrapper type that the [`Router`](crate::Router) uses to interact with a [`History`].
 /// This is automatically provided in the browser. For the server, it should be provided
 /// as a context. Be sure that it can survive conversion to a URL in the browser.
 ///

router/src/history/params.rs

@@ -4,9 +4,12 @@ use std::{str::FromStr, sync::Arc};
 use thiserror::Error;
 
 /// A key-value map of the current named route params and their values.
-// For now, implemented with a `LinearMap`, as `n` is small enough
-// that O(n) iteration over a vectorized map is (*probably*) more space-
-// and time-efficient than hashing and using an actual `HashMap`
+///
+/// For now, implemented with a [`LinearMap`], as `n` is small enough
+/// that O(n) iteration over a vectorized map is (*probably*) more space-
+/// and time-efficient than hashing and using an actual `HashMap`
+///
+/// [`LinearMap`]: linear_map::LinearMap
 #[derive(Debug, PartialEq, Eq, Clone, Deserialize, Serialize)]
 #[repr(transparent)]
 pub struct ParamsMap(pub LinearMap<String, String>);
@@ -69,7 +72,7 @@ impl Default for ParamsMap {
     }
 }
 
-/// A declarative way of creating a [ParamsMap].
+/// A declarative way of creating a [`ParamsMap`].
 ///
 /// ```
 /// # use leptos_router::params_map;
@@ -98,7 +101,7 @@ macro_rules! params_map {
 
 /// A simple method of deserializing key-value data (like route params or URL search)
 /// into a concrete data type. `Self` should typically be a struct in which
-/// each field's type implements [FromStr].
+/// each field's type implements [`FromStr`].
 pub trait Params
 where
     Self: Sized,
@@ -159,7 +162,7 @@ cfg_if::cfg_if! {
     }
 }
 
-/// Errors that can occur while parsing params using [Params](crate::Params).
+/// Errors that can occur while parsing params using [`Params`].
 #[derive(Error, Debug, Clone)]
 pub enum ParamsError {
     /// A field was missing from the route params.

router/src/hooks.rs

@@ -7,6 +7,7 @@ use leptos::{
     Oco,
 };
 use std::{rc::Rc, str::FromStr};
+
 /// Constructs a signal synchronized with a specific URL query parameter.
 ///
 /// The function creates a bidirectional sync mechanism between the state encapsulated in a signal and a URL query parameter.
@@ -82,7 +83,7 @@ where
     (get, set)
 }
 
-/// Returns the current [RouterContext], containing information about the router's state.
+/// Returns the current [`RouterContext`], containing information about the router's state.
 #[track_caller]
 pub fn use_router() -> RouterContext {
     if let Some(router) = use_context::<RouterContext>() {
@@ -96,7 +97,7 @@ pub fn use_router() -> RouterContext {
     }
 }
 
-/// Returns the current [RouteContext], containing information about the matched route.
+/// Returns the current [`RouteContext`], containing information about the matched route.
 #[track_caller]
 pub fn use_route() -> RouteContext {
     use_context::<RouteContext>().unwrap_or_else(|| use_router().base())
@@ -112,7 +113,7 @@ pub fn use_route_data<T: Clone + 'static>() -> Option<T> {
     downcast
 }
 
-/// Returns the current [Location], which contains reactive variables
+/// Returns the current [`Location`], which contains reactive variables
 #[track_caller]
 pub fn use_location() -> Location {
     use_router().inner.location.clone()

router/src/lib.rs

@@ -3,8 +3,8 @@
 //! # Leptos Router
 //!
 //! Leptos Router is a router and state management tool for web applications
-//! written in Rust using the [Leptos](https://github.com/leptos-rs/leptos) web framework.
-//! It is ”isomorphic,” i.e., it can be used for client-side applications/single-page
+//! written in Rust using the [`Leptos`] web framework.
+//! It is ”isomorphic”, i.e., it can be used for client-side applications/single-page
 //! apps (SPAs), server-side rendering/multi-page apps (MPAs), or to synchronize
 //! state between the two.
 //!
@@ -19,7 +19,7 @@
 //!    and are rendered by different components. This means you can navigate between siblings
 //!    in this tree without re-rendering or triggering any change in the parent routes.
 //!
-//! 3. **Progressive enhancement.** The [A] and [Form] components resolve any relative
+//! 3. **Progressive enhancement.** The [`A`] and [`Form`] components resolve any relative
 //!    nested routes, render actual `<a>` and `<form>` elements, and (when possible)
 //!    upgrading them to handle those navigations with client-side routing. If you’re using
 //!    them with server-side rendering (with or without hydration), they just work,
@@ -35,7 +35,7 @@
 //! #[component]
 //! pub fn RouterExample() -> impl IntoView {
 //!   view! {
-//!     
+//!
 //!     <div id="root">
 //!       // we wrap the whole app in a <Router/> to allow client-side navigation
 //!       // from our nav links below
@@ -100,7 +100,7 @@
 //!   // loads the contact list data once; doesn't reload when nested routes change
 //!   let contacts = create_resource(|| (), |_| contact_list_data());
 //!   view! {
-//!     
+//!
 //!     <div>
 //!       // show the contacts
 //!       <ul>
@@ -117,7 +117,7 @@
 //! fn Contact() -> impl IntoView {
 //!   let params = use_params_map();
 //!   let data = create_resource(
-//!     
+//!
 //!     move || params.with(|p| p.get("id").cloned().unwrap_or_default()),
 //!     move |id| contact_data(id)
 //!   );
@@ -182,6 +182,8 @@
 //!
 //! **Important Note:** You must enable one of `csr`, `hydrate`, or `ssr` to tell Leptos
 //! which mode your app is operating in.
+//!
+//! [`Leptos`]: <https://github.com/leptos-rs/leptos>
 
 #![cfg_attr(feature = "nightly", feature(auto_traits))]
 #![cfg_attr(feature = "nightly", feature(negative_impls))]

router/src/matching/matcher.rs

@@ -1,5 +1,5 @@
 // Implementation based on Solid Router
-// see https://github.com/solidjs/solid-router/blob/main/src/utils.ts
+// see <https://github.com/solidjs/solid-router/blob/main/src/utils.ts>
 
 use crate::ParamsMap;
 

router/src/matching/resolve_path.rs

@@ -1,5 +1,5 @@
 // Implementation based on Solid Router
-// see https://github.com/solidjs/solid-router/blob/main/src/utils.ts
+// see <https://github.com/solidjs/solid-router/blob/main/src/utils.ts>
 
 use std::borrow::Cow;