yewstack · siku2 · Aug 29, 2020 · Aug 27, 2020 · Aug 27, 2020 · Aug 28, 2020
diff --git a/yew/src/lib.rs b/yew/src/lib.rs
@@ -97,9 +97,101 @@
 extern crate self as yew;
 
 /// This macro implements JSX-like templates.
+///
+/// This macro erases the component type and always returns [`Html`].
+/// If you want non-erased type, look at [`html_nested!`] macro.
+///
+/// More information about using the `html!` macro can be found in yew's [manual].
+///
+/// [`Html`]: ./html/type.Html.html
+/// [`html_nested!`]: ./macro.html_nested.html
+/// [manual]: https://yew.rs/docs/en/concepts/html/
 pub use yew_macro::html;
 
-#[doc(hidden)]
+/// This macro is similar to [`html!`], but returns actual component type instead
+/// of a generic [`Html`].
+///
+/// That macro is useful when, for example, in a typical implementation of a list
+/// component (let's assume it's called `List`). In a typical implementation you
+/// would have two connected components -- `List` and `ListItem`, and `List`'s
+/// children would be a number of `ListItem`s.
+///
+/// You can find an example implementation of this in the [`nested_list`] example.
+/// That example shows, how to create static lists with their children, but in
+/// most use cases the contents of a list is dynamic and thus known only at runtime.
+///
+/// ```
+/// # use yew::prelude::*;
+/// use yew::html::ChildrenRenderer;
+/// use yew::virtual_dom::VChild;
+///
+/// #[derive(Clone, Properties)]
+/// struct List {
+///   children: ChildrenRenderer<ListItem>,
+/// }
+/// impl Component for List {
+/// #   type Message = ();
+///   type Properties = Self;
+///   // ...
+/// #   fn create(props: Self::Properties, _: ComponentLink<Self>) -> Self { props }
+/// #   fn update(&mut self, _: Self::Message) -> ShouldRender { false }
+/// #   fn change(&mut self, _: Self::Properties) -> ShouldRender { false }
+/// #   fn view(&self) -> Html { unimplemented!() }
+/// }
+///
+/// #[derive(Clone)]
+/// struct ListItem;
+/// impl Component for ListItem {
+/// #   type Message = ();
+/// #   type Properties = ();
+///   // ...
+/// #   fn create(_: Self::Properties, _: ComponentLink<Self>) -> Self { Self }
+/// #   fn update(&mut self, _: Self::Message) -> ShouldRender { false }
+/// #   fn change(&mut self, _: Self::Properties) -> ShouldRender { false }
+/// #   fn view(&self) -> Html { unimplemented!() }
+/// }
+///
+/// // Required for ChildrenRenderer
+/// impl From<VChild<ListItem>> for ListItem {
+///   fn from(child: VChild<ListItem>) -> Self { Self }
+/// }
+///
+/// impl Into<Html> for ListItem {
+///   fn into(self) -> Html { self.view() }
+/// }
+///
+/// // Manually you create list by just nesting `ListItem`'s into `List`:
+/// # fn test() -> Html {
+/// html! {
+///   <List>
+///     <ListItem/>
+///     <ListItem/>
+///     <ListItem/>
+///   </List>
+/// }
+/// # }
+/// # fn test_iter() -> Html {
+/// # let some_iter = (0..10);
+/// // In many cases you might want to create the content dynamically.
+/// // To do this, you can use the following code:
+/// html! {
+///   <List>
+///     { for some_iter.map(|_| html_nested!{ <ListItem/> }) }
+///   </List>
+/// }
+/// # }
+/// ```
+///
+/// If you used the [`html!`] macro instead of `html_nested!`, the code would
+/// not compile because we explicitly indicated to the compiler that `List`
+/// can only contain elements of type `ListItem` using [`ChildrenRenderer<ListItem>`],
+/// while [`html!`] creates items of type [`Html`].
+///
+///
+/// [`html!`]: ./macro.html.html
+/// [`Html`]: ./html/type.Html.html
+/// [`nested_list`]: https://github.com/yewstack/yew/tree/master/examples/nested_list
+/// [`ChildrenRenderer<ListItem>`]: ./html/struct.ChildrenRenderer.html
 pub use yew_macro::html_nested;
 
 /// This module contains macros which implements html! macro and JSX-like templates