From 57a00a33a380b49d10ab15b05ac89a9c19b3dd80 Mon Sep 17 00:00:00 2001
From: Spencer Ferris <3319370+spencewenski@users.noreply.github.com>
Date: Wed, 26 Jun 2024 14:57:40 -0700
Subject: [PATCH] docs: Add docs for `ToChildren` (#2643)

* docs: Add docs for `ToChildren`

As discussed in https://github.com/leptos-rs/leptos/discussions/2640,
the `ToChildren` trait is useful to consumers who want to use the
builder syntax. However, because it is currently annotated with
`#[docs(hidden)]`, it's not visible in docs and also not included in
Jetbrains's auto-complete.

Add a doc comment for the `ToChildren` trait, including doc tests that
demonstrate how to use the trait and how it compares to directly
creating children.

* docs: Fix incorrect examples in `ToChildren` docs

Some examples were added to `ToChildren` that don't compile. This
wasn't caught earlier because no errors were seen in the IDE when
writing the examples. The issue was correctly caught by CI, however.
---
 leptos/src/children.rs | 74 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/leptos/src/children.rs b/leptos/src/children.rs
index 2d369cf21..404a0e59d 100644
--- a/leptos/src/children.rs
+++ b/leptos/src/children.rs
@@ -16,8 +16,80 @@ pub type ChildrenFnMut = Box<dyn FnMut() -> Fragment>;
 // This is to still support components that accept `Box<dyn Fn() -> Fragment>` as a children.
 type BoxedChildrenFn = Box<dyn Fn() -> Fragment>;
 
-#[doc(hidden)]
+/// This trait can be used when constructing a component that takes children without needing
+/// to know exactly what children type the component expects. This is used internally by the
+/// `view!` macro implementation, and can also be used explicitly when using the builder syntax.
+///
+/// # Examples
+///
+/// ## Without ToChildren
+///
+/// Without [ToChildren], consumers need to explicitly provide children using the type expected
+/// by the component. For example, [Provider][crate::Provider]'s children need to wrapped in
+/// a [Box], while [Show][crate::Show]'s children need to be wrapped in an [Rc].
+///
+/// ```
+/// # use leptos::{ProviderProps, ShowProps};
+/// # use leptos_dom::html::p;
+/// # use leptos_dom::IntoView;
+/// # use leptos_macro::component;
+/// # use std::rc::Rc;
+/// #
+/// #[component]
+/// fn App() -> impl IntoView {
+///     (
+///         ProviderProps::builder()
+///             .children(Box::new(|| p().child("Foo").into_view().into()))
+///             // ...
+/// #           .value("Foo")
+/// #           .build(),
+///         ShowProps::builder()
+///             .children(Rc::new(|| p().child("Foo").into_view().into()))
+///             // ...
+/// #           .when(|| true)
+/// #           .fallback(|| p().child("foo"))
+/// #           .build(),
+///     )
+/// }
+/// ```
+///
+/// ## With ToChildren
+///
+/// With [ToChildren], consumers don't need to know exactly which type a component uses for
+/// its children.
+///
+/// ```
+/// # use leptos::{ProviderProps, ShowProps};
+/// # use leptos_dom::html::p;
+/// # use leptos_dom::IntoView;
+/// # use leptos_macro::component;
+/// # use std::rc::Rc;
+/// # use leptos::ToChildren;
+/// #
+/// #[component]
+/// fn App() -> impl IntoView {
+///     (
+///         ProviderProps::builder()
+///             .children(ToChildren::to_children(|| {
+///                 p().child("Foo").into_view().into()
+///             }))
+///             // ...
+/// #           .value("Foo")
+/// #           .build(),
+///         ShowProps::builder()
+///             .children(ToChildren::to_children(|| {
+///                 p().child("Foo").into_view().into()
+///             }))
+///             // ...
+/// #           .when(|| true)
+/// #           .fallback(|| p().child("foo"))
+/// #           .build(),
+///     )
+/// }
 pub trait ToChildren<F> {
+    /// Convert the provided type to (generally a closure) to Self (generally a "children" type,
+    /// e.g., [Children]). See the implementations to see exactly which input types are supported
+    /// and which "children" type they are converted to.
     fn to_children(f: F) -> Self;
 }