From a8ea2ccd0b9601728c0b917645e3e4d8ab12dbb4 Mon Sep 17 00:00:00 2001
From: Jared Moulton <jaredmoulton3@gmail.com>
Date: Sun, 20 Aug 2023 01:44:52 -0600
Subject: [PATCH] Add docs for container Views (#91)

---
 src/lib.rs                 |  5 ++++-
 src/views/container.rs     |  5 +++++
 src/views/container_box.rs | 37 +++++++++++++++++++++++++++++++++++++
 src/views/dyn_container.rs |  3 ++-
 src/views/mod.rs           |  2 +-
 5 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index e69b4359..846693ff 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -73,7 +73,10 @@
 //!
 //! ## More
 //!
-//! #### Authoring your own custom [Views](view::View)
+//! #### Check out all of the built-in [View](view::View)s
+//! See the [Views module](views) for more info.
+//!
+//! #### Authoring your own custom [View](view::View)s
 //! See the [View module](view) for more info.
 //!
 //! #### Understanding Ids
diff --git a/src/views/container.rs b/src/views/container.rs
index 6d9b547e..b36d123e 100644
--- a/src/views/container.rs
+++ b/src/views/container.rs
@@ -6,11 +6,16 @@ use crate::{
     view::{ChangeFlags, View},
 };
 
+/// A simple wrapper around another View. See [`container`]
 pub struct Container<V: View> {
     id: Id,
     child: V,
 }
 
+/// A simple wrapper around another View
+///
+/// A [`Container`] is useful for wrapping another [View](crate::view::View). This is often useful for allowing another
+/// set of styles completely separate from the View that is being wrapped.
 pub fn container<V: View>(child: impl FnOnce() -> V) -> Container<V> {
     let (id, child) = ViewContext::new_id_with_child(child);
     Container { id, child }
diff --git a/src/views/container_box.rs b/src/views/container_box.rs
index 801a3ed6..ff2b7284 100644
--- a/src/views/container_box.rs
+++ b/src/views/container_box.rs
@@ -6,11 +6,48 @@ use crate::{
     view::{ChangeFlags, View},
 };
 
+/// A wrapper around any type that implements View. See [`container_box`]
 pub struct ContainerBox {
     id: Id,
     child: Box<dyn View>,
 }
 
+/// A wrapper around any type that implements View.
+///
+/// Views in Floem are strongly typed. A [`ContainerBox`] allows you to escape the strongly typed View and contain a `Box<dyn View>`.
+///
+/// ## Bad Example
+///```compile_fail
+/// use floem::views::*;
+/// use floem_reactive::*;
+/// let check = true;
+///
+/// container(|| {
+///     if check == true {
+///         checkbox(create_rw_signal(true).read_only())
+///     } else {
+///         label(|| "no check".to_string())
+///     }
+/// });
+/// ```
+/// The above example will fail to compile because the container is strongly typed so the if and
+/// the else must return the same type. The problem is that checkbox is an [Svg](crate::views::Svg)
+/// and the else returns a [Label](crate::views::Label). The solution to this is to use a
+/// [`ContainerBox`] to escape the strongly typed requirement.
+///
+/// ```
+/// use floem::views::*;
+/// use floem_reactive::*;
+/// let check = true;
+///
+/// container_box(|| {
+///     if check == true {
+///         Box::new(checkbox(create_rw_signal(true).read_only()))
+///     } else {
+///         Box::new(label(|| "no check".to_string()))
+///     }
+/// });
+/// ```
 pub fn container_box(child: impl FnOnce() -> Box<dyn View>) -> ContainerBox {
     let (id, child) = ViewContext::new_id_with_child(child);
     ContainerBox { id, child }
diff --git a/src/views/dyn_container.rs b/src/views/dyn_container.rs
index eb14bcc1..35dbd676 100644
--- a/src/views/dyn_container.rs
+++ b/src/views/dyn_container.rs
@@ -20,7 +20,6 @@ pub struct DynamicContainer<T: 'static> {
 
 /// A container for a dynamically updating View
 ///
-///
 /// ## Example
 /// ```ignore
 /// #[derive(Debug, Clone)]
@@ -70,6 +69,8 @@ pub struct DynamicContainer<T: 'static> {
 ///     })
 /// }
 /// ```
+///
+/// See [container_box](crate::views::container_box()) for more documentation on a general container
 pub fn dyn_container<CF: Fn(T) -> Box<dyn View> + 'static, T: 'static>(
     update_view: impl Fn() -> T + 'static,
     child_fn: CF,
diff --git a/src/views/mod.rs b/src/views/mod.rs
index d6752b0b..c01cd8a1 100644
--- a/src/views/mod.rs
+++ b/src/views/mod.rs
@@ -1,6 +1,6 @@
 //! # Floem builtin Views
 //!
-//! This module contains all of the builting Views or Components of Floem.
+//! This module contains all of the built-in Views of Floem.
 //!
 
 mod label;