Improve main module (lib.rs) docs + re-export more types at the crate…

… root (#444)

* Write top-level module documentation to replace README

* Remove badges from module documentation

* Update docs to reflect changes to main

* Re-export almost all types at the top-level module

* Improve one-line docs for Taffy and Style structs

* Remove internal use of prelude in non-test modules

* Add examples to lib.rs docs

src/compute/flexbox.rs

@@ -1,12 +1,12 @@
 //! Computes the [flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) layout algorithm on [`Taffy`](crate::Taffy) according to the [spec](https://www.w3.org/TR/css-flexbox-1/)
 use crate::compute::common::alignment::compute_alignment_offset;
 use crate::geometry::{Line, Point, Rect, Size};
-use crate::prelude::{TaffyMaxContent, TaffyMinContent};
 use crate::style::{
     AlignContent, AlignItems, AlignSelf, AvailableSpace, Dimension, Display, FlexWrap, JustifyContent,
     LengthPercentageAuto, Overflow, Position,
 };
 use crate::style::{FlexDirection, Style};
+use crate::style_helpers::{TaffyMaxContent, TaffyMinContent};
 use crate::tree::{Layout, LayoutInput, LayoutOutput, RunMode, SizingMode};
 use crate::tree::{NodeId, PartialLayoutTree, PartialLayoutTreeExt};
 use crate::util::debug::debug_log;

src/lib.rs

@@ -1,4 +1,61 @@
-#![doc = include_str!("../README.md")]
+//! # Taffy
+//!
+//! Taffy is a flexible, high-performance library for **UI layout**.
+//! It currently implements the Block, Flexbox and Grid layout algorithms from the CSS specification. Support for other paradigms is planned.
+//! For more information on this and other future development plans see the [roadmap issue](https://github.com/DioxusLabs/taffy/issues/345).
+//!
+//! ## Architecture
+//!
+//! Taffy is based on a tree of "UI nodes" similar to the tree of DOM nodes that one finds in web-based UI. Each node has:
+//!   - A [`Style`] struct which holds a set of CSS styles which function as the primary input to the layout computations.
+//!   - A [`Layout`] struct containing a position (x/y) and a size (width/height) which function as the output of the layout computations.
+//!   - Optionally:
+//!       - A `Vec` set of child nodes
+//!       - "Context": arbitary user-defined data (which you can access when using a "measure function" to integrate Taffy with other kinds of layout such as text layout)
+//!
+//! Usage of Taffy consists of constructing a tree of UI nodes (with associated styles, children and context), then calling function(s)
+//! from Taffy to translate those styles, parent-child relationships and measure functions into a size and position in 2d space for each node
+//! in the tree.
+//!
+//! ## High-level API vs. Low-level API
+//!
+//! Taffy has two APIs: a high-level API that is simpler and easier to get started with, and a low-level API that is more flexible gives greater control.
+//!
+//! We would generally recommend the high-level API for users using Taffy standalone and the low-level API for users wanting to embed Taffy as part of
+//! a wider layout system or as part of a UI framework that already has it's own node/widget tree representation.
+//!
+//! ### High-level API
+//!
+//! The high-level API** consists of the [`Taffy`] struct which contains a tree implementation and provides methods that allow you to construct
+//! a tree of UI nodes. Once constructed, you can call the [`compute_layout_with_measure`](crate::Taffy::compute_layout_with_measure) method to compute the layout (passing in a "measure function" closure which is used to compute the size of leaf nodes), and then access
+//! the layout of each node using the [`layout`](crate::Taffy::layout) method.
+//!
+//! When using the high-level API, Taffy will take care of node storage, caching and dispatching to the correct layout algorithm for a given node for you.
+//! See the [`Taffy`] struct for more details on this API.
+//!
+//! Examples which show usage of the high-level API include:
+//!
+//!   - [basic](https://github.com/DioxusLabs/taffy/blob/main/examples/basic.rs)
+//!   - [flexbox_gap](https://github.com/DioxusLabs/taffy/blob/main/examples/flexbox_gap.rs)
+//!   - [grid_holy_grail](https://github.com/DioxusLabs/taffy/blob/main/examples/basic.rs)
+//!   - [measure](https://github.com/DioxusLabs/taffy/blob/main/examples/measure.rs)
+//!
+//! In particular, the "measure" example shows how to integrate Taffy layout with other layout modalities such as text or image layout when using the high level API.
+//!
+//! ### Low-level API
+//!
+//! The low-level API consists of a set of traits (notably the [`PartialLayoutTree`] trait) which define an interface behind which you must implement your own
+//! tree implementation, and a set of functions such as [`compute_flexbox_layout`] and [`compute_grid_layout`] which implement the layout algorithms (for a single node at a time), and are designed to be flexible
+//! and easy to integrate into a wider layout or UI system.
+//!
+//! When using this API, you must handle node storage, caching, and dispatching to the correct layout algorithm for a given node yourself.
+//! See the [`PartialLayoutTree`] trait for more details on this API.
+//!
+//! Examples which show usage of the high-level API are:
+//!
+//!   - [custom_layout_tree_vec](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_layout_tree_vec.rs) which implements a custom Taffy tree using a `Vec` as an arena with NodeId's being index's into the Vec.
+//!   - [custom_layout_tree_owned](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_layout_tree_owned.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 #![deny(unsafe_code)]
 #![forbid(unsafe_code)]
@@ -27,15 +84,35 @@ pub mod tree;
 #[macro_use]
 pub mod util;
 
+mod readme_doctest {
+    #![doc = include_str!("../README.md")]
+}
+
 #[cfg(feature = "block_layout")]
+#[doc(inline)]
 pub use crate::compute::compute_block_layout;
 #[cfg(feature = "flexbox")]
+#[doc(inline)]
 pub use crate::compute::compute_flexbox_layout;
 #[cfg(feature = "grid")]
+#[doc(inline)]
 pub use crate::compute::compute_grid_layout;
+#[doc(inline)]
 pub use crate::compute::{
     compute_cached_layout, compute_hidden_layout, compute_layout, compute_leaf_layout, round_layout,
 };
-pub use crate::tree::{LayoutTree, PartialLayoutTree};
+#[doc(inline)]
+pub use crate::style::Style;
 #[cfg(feature = "taffy_tree")]
-pub use crate::tree::{Taffy, TaffyError, TaffyResult};
+#[doc(inline)]
+pub use crate::tree::Taffy;
+#[doc(inline)]
+pub use crate::tree::{LayoutTree, PartialLayoutTree};
+#[cfg(feature = "std")]
+#[doc(inline)]
+pub use crate::util::print_tree;
+
+pub use crate::geometry::*;
+pub use crate::style::*;
+pub use crate::tree::*;
+pub use crate::util::*;

src/style/mod.rs

@@ -169,7 +169,7 @@ impl Overflow {
     }
 }
 
-/// The flexbox layout information for a single node.
+/// A typed representation of the CSS style information for a single node.
 ///
 /// The most important idea in flexbox is the notion of a "main" and "cross" axis, which are always perpendicular to each other.
 /// The orientation of these axes are controlled via the [`FlexDirection`] field of this struct.

src/tree/layout.rs

@@ -1,7 +1,7 @@
 //! Final data structures that represent the high-level UI layout
 use crate::geometry::{AbsoluteAxis, Line, Point, Rect, Size};
-use crate::prelude::TaffyMaxContent;
 use crate::style::AvailableSpace;
+use crate::style_helpers::TaffyMaxContent;
 use crate::util::sys::{f32_max, f32_min};
 
 /// Whether we are performing a full layout, or we merely need to size the node

src/tree/taffy_tree.rs

@@ -68,7 +68,9 @@ impl Default for TaffyConfig {
     }
 }
 
-/// A tree of UI nodes suitable for UI layout
+/// An entire tree of UI nodes. The entry point to Taffy's high-level API.
+///
+/// Allows you to build a tree of UI nodes, run Taffy's layout algorithms over that tree, and then access the resultant layout.
 pub struct Taffy<NodeContext = ()> {
     /// The [`NodeData`] for each node stored in this tree
     pub(crate) nodes: SlotMap<DefaultKey, NodeData>,