Add docs for container Views

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

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 }

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 }

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,

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;