@@ -4,7 +4,45 @@ use std::any::Any;
44use std::rc::Rc;
55use wasm_bindgen::UnwrapThrowExt;
66
7+/// A trait for any component that can be rendered to HTML.
8+///
9+/// Takes a shared reference to `self` and generates the virtual DOM that
10+/// represents its rendered HTML.
11+///
12+/// ## `Bump` Allocation
13+///
14+/// `Render` implementations can use the provided `Bump` for very fast
15+/// allocation for anything that needs to be allocated during rendering.
16+///
17+/// ## The `'a: 'bump` Lifetime Bound
18+///
19+/// The `'a: 'bump` bounds enforce that `self` outlives the given bump
20+/// allocator. This means that if `self` contains a string, the string does not
21+/// need to be copied into the output `Node` and can be used by reference
22+/// instead (i.e. it prevents accidentally using the string after its been
23+/// freed). The `'a: 'bump` bound also enables abstractions like
24+/// `dodrio::Cached` that can re-use cached `Node`s across `render`s without
25+/// copying them.
26+///
27+/// ## Example
28+///
29+/// ```no_run
30+/// use dodrio::{Bump, Node, Render};
31+///
32+/// pub struct MyComponent;
33+///
34+/// impl Render for MyComponent {
35+/// fn render<'a, 'bump>(&'a self, bump: &'bump Bump) -> Node<'bump>
36+/// where
37+/// 'a: 'bump
38+/// {
39+/// Node::text("This is my component rendered!")
40+/// }
41+/// }
42+/// ```
743pub trait Render {
44+ /// Render `self` as a virtual DOM. Use the given `Bump` for temporary
45+ /// allocations.
846 fn render<'a, 'bump>(&'a self, bump: &'bump Bump) -> Node<'bump>
947 where
1048 'a: 'bump;