Better doc

src/view/identifiable.rs

@@ -8,6 +8,34 @@ pub trait Identifiable: View + Sized {
     /// Wraps this view into an `IdView` with the given id.
     ///
     /// This is just a shortcut for `IdView::new(id, self)`
+    ///
+    /// You can use the given id to find the view in the layout tree.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// let mut siv = Cursive::new();
+    /// siv.add_layer(
+    ///     TextView::new("foo")
+    ///         .with_id("text")
+    ///         .fixed_width(10)
+    /// );
+    ///
+    /// // You could call this from an event callback
+    /// siv.call_on_id("text", |view: &mut TextView| {
+    ///     view.set_content("New content!");
+    /// });
+    /// ```
+    ///
+    /// # Notes
+    ///
+    /// You should call this directly on the view you want to retrieve later,
+    /// before other wrappers like [`fixed_width`]. Otherwise, you would be
+    /// retrieving a [`BoxView`]!
+    ///
+    /// [`fixed_width`]: trait.Boxable.html#method.fixed_width
+    /// [`BoxView`]: ../views/struct.BoxView.html
+    ///
     fn with_id<S: Into<String>>(self, id: S) -> IdView<Self> {
         IdView::new(id, self)
     }

src/view/view_wrapper.rs

@@ -7,11 +7,16 @@ use view::{Selector, View};
 
 /// Generic wrapper around a view.
 ///
-/// Default implementation forwards all calls to the child view.
-/// Overrides some methods as desired.
+/// This trait is a shortcut to implement `View` on a type by forwarding
+/// calls to a wrapped view.
 ///
-/// You can use the [`wrap_impl!`] macro to define `with_view` and
-/// `with_view_mut` for you.
+/// You only need to define `with_view` and `with_view_mut`
+/// (the [`wrap_impl!`] macro can help you with that), and you will get
+/// the `View` implementation for free.
+///
+/// You can also override any of the `wrap_*` methods for more specific
+/// behaviors (the default implementations simply forwards the calls to the
+/// child view).
 ///
 /// [`wrap_impl!`]: ../macro.wrap_impl.html
 pub trait ViewWrapper: 'static {