[rust] update docs

- add more NcPlane docs.
- minor fixes.

rust/src/notcurses/methods.rs

@@ -587,7 +587,7 @@ impl Notcurses {
         }
     }
 
-    /// Allocates an ncstats object.
+    /// Allocates an [`NcStats`] object.
     ///
     /// Use this rather than allocating your own, since future versions of
     /// Notcurses might enlarge this structure.

rust/src/plane/mod.rs

@@ -194,36 +194,64 @@ pub use reimplemented::*;
 /// `type in C: ncplane (struct)`
 ///
 ///
-/// # Piles
+/// # About planes and piles
 ///
-/// A single notcurses context is made up of one or more piles.
+/// A given notcurses context is made up of one or more piles.
 ///
-/// A pile is a set of one or more ncplanes, including the partial orderings
-/// made up of their binding and z-axis pointers.
+/// A pile is made up of [`NcPlane`]s, totally ordered on a z-axis.
 ///
-/// A pile has a top and bottom ncplane (this might be a single plane),
-/// and one or more root planes (planes which are bound to themselves).
+/// You can't manage the piles directly, but only the `NcPlanes`.
 ///
-/// Multiple threads can concurrently operate on distinct piles, even changing
-/// one while rendering another.
+/// A pile is destroyed when all its planes are destroyed or moved to other
+/// piles.
 ///
-/// Each plane is part of one and only one pile. By default, a plane is part of
-/// the same pile containing that plane to which it is bound.
+/// A pile has a top and bottom plane (this might be a single `NcPlane`),
+/// and one or more root planes (`NcPlane`s which are bound to themselves).
 ///
-/// If ncpile_create is used in the place of ncplane_create, the returned plane
-/// becomes the root plane, top, and bottom of a new pile.  As a root plane,
+/// Multiple threads can concurrently operate on distinct piles, rendering or
+/// mutating it, while another thread concurrently renders or mutates another.
+///
+/// Each `NcPlane` is part of one and only one pile. By default, an `NcPlane` is
+/// part of the same pile that contains the `NcPlane` to which it is bound.
+///
+/// When an `NcPlane` is created without being bound to another `NcPlane`, then
+/// it becomes the root plane, top, and bottom of a new pile. As a root plane,
 /// it is bound to itself.
 ///
-/// A new pile can also be created by reparenting a plane to itself,
+/// A new pile can also be created by reparenting an `NcPlane` to itself,
 /// though if the plane is already a root plane, this is a no-op.
 ///
-/// When a plane is moved to a different pile (whether new or preexisting),
-/// any planes which were bound to it are rebound to its previous parent.
-/// If the plane was a root plane of some pile, any bound planes become root
-/// planes. The new plane is placed immediately atop its new parent on its new
-/// pile's z-axis. When ncplane_reparent_family() is used, all planes bound to
-/// the reparented plane are moved along with it. Their relative z-order is maintained.
+/// When an `NcPlane` is moved to a different pile (whether new or preexisting),
+/// any `NcPlane`s which were bound to it are rebound to its previous parent.
+/// If the `NcPlane` was a root plane of some pile, any bound planes become root
+/// planes. The new `NcPlane` is placed immediately atop its new parent on its
+/// new pile's z-axis.
+///
+/// When [`NcPlane::reparent_family`][NcPlane#method.reparent_family] is used,
+/// all `NcPlanes` bound to the reparented `NcPlane` are moved along with it.
+/// Their relative z-order is maintained.
+//
+/// Rendering reduces a pile of `NcPlane`s to a single `NcPlane`, proceeding
+/// from the top to the bottom along a pile's z-axis. The result is a matrix of
+/// [`NcCell`][crate::NcCell]s. Rasterizing takes this matrix, together with the
+/// current state of the visual area, and produces a stream of optimized control
+/// sequences and [`NcEgc`][crate::NcEgc]s for the terminal. By writing this
+/// stream to the terminal, the physical display is synced to some pile's
+/// `NcPlane`s.
+///
+/// [`NcPlane.render`][crate::NcPlane#method.render] performs the first of these
+/// tasks for the pile of which the plane is a part. The output is maintained
+/// internally; calling `render` again on the same pile will replace this state
+/// with a fresh render. Multiple piles can be concurrently rendered.
+/// [`NcPlane.rasterize`][crate::NcPlane#method.rasterize] performs
+/// rasterization, and writes the result to the terminal. It is a blocking call,
+/// and only one rasterization operation may proceed at a time.
 ///
+/// It is necessary to call `NcPlane.rasterize` to generate any visible output;
+/// the various *output calls* only draw to the virtual `NcPlane`s. Most of the
+/// notcurses `statistics` are updated as a result of a render, and screen
+/// geometry is refreshed (similarly to
+/// [`Notcurses.refresh`][crate::Notcurses#method.refresh]) following the render.
 ///
 /// # Methods & Associated Functions
 ///