Formatting, documentation and small improvements 🧽

1 files changed, 50 insertions, 56 deletions

diff --git a/src/layout/mod.rs b/src/layout/mod.rs
index 143f1984..8a68a6a5 100644
--- a/src/layout/mod.rs
+++ b/src/layout/mod.rs
@@ -1,37 +1,37 @@
-//! Layouting types and engines.
-
-use async_trait::async_trait;
-
-use crate::Pass;
-use crate::font::SharedFontLoader;
-use crate::geom::{Size, Margins};
-use crate::style::{LayoutStyle, TextStyle, PageStyle};
-use crate::syntax::tree::SyntaxTree;
-
-use elements::LayoutElements;
-use tree::TreeLayouter;
-use prelude::*;
+//! Layouting of syntax trees into box layouts.
 
 pub mod elements;
 pub mod line;
 pub mod primitive;
 pub mod stack;
 pub mod text;
-pub mod tree;
-
-pub use primitive::*;
+mod tree;
 
 /// Basic types used across the layouting engine.
 pub mod prelude {
-    pub use super::layout;
     pub use super::primitive::*;
+    pub use super::layout;
     pub use Dir::*;
-    pub use GenAxis::*;
-    pub use SpecAxis::*;
     pub use GenAlign::*;
+    pub use GenAxis::*;
     pub use SpecAlign::*;
+    pub use SpecAxis::*;
 }
 
+pub use primitive::*;
+pub use tree::layout_tree as layout;
+
+use async_trait::async_trait;
+
+use crate::font::SharedFontLoader;
+use crate::geom::{Margins, Size};
+use crate::style::{LayoutStyle, PageStyle, TextStyle};
+use crate::syntax::tree::SyntaxTree;
+use crate::Pass;
+
+use elements::LayoutElements;
+use prelude::*;
+
 /// A collection of layouts.
 pub type MultiLayout = Vec<BoxLayout>;
 
@@ -40,47 +40,41 @@ pub type MultiLayout = Vec<BoxLayout>;
 pub struct BoxLayout {
     /// The size of the box.
     pub size: Size,
-    /// How to align this layout in a parent container.
+    /// How to align this box in a parent container.
     pub align: LayoutAlign,
     /// The elements composing this layout.
     pub elements: LayoutElements,
 }
 
-/// Layouting of elements.
+/// Comamnd-based layout.
 #[async_trait(?Send)]
 pub trait Layout {
-    /// Layout self into a sequence of layouting commands.
-    async fn layout<'a>(&'a self, _: LayoutContext<'_>) -> Pass<Commands<'a>>;
-}
-
-/// Layout a syntax tree into a list of boxes.
-pub async fn layout(tree: &SyntaxTree, ctx: LayoutContext<'_>) -> Pass<MultiLayout> {
-    let mut layouter = TreeLayouter::new(ctx);
-    layouter.layout_tree(tree).await;
-    layouter.finish()
+    /// Create a sequence of layouting commands to execute.
+    async fn layout<'a>(&'a self, ctx: LayoutContext<'_>) -> Pass<Commands<'a>>;
 }
 
 /// The context for layouting.
 #[derive(Debug, Clone)]
 pub struct LayoutContext<'a> {
-    /// The font loader to retrieve fonts from when typesetting text
-    /// using [`layout_text`].
+    /// The font loader to query fonts from when typesetting text.
     pub loader: &'a SharedFontLoader,
     /// The style for pages and text.
     pub style: &'a LayoutStyle,
-    /// The base unpadded size of this container (for relative sizing).
+    /// The unpadded size of this container (the base 100% for relative sizes).
     pub base: Size,
-    /// The spaces to layout in.
+    /// The spaces to layout into.
     pub spaces: LayoutSpaces,
-    /// Whether to have repeated spaces or to use only the first and only once.
+    /// Whether to spill over into copies of the last space or finish layouting
+    /// when the last space is used up.
     pub repeat: bool,
-    /// The initial axes along which content is laid out.
+    /// The axes along which content is laid out.
     pub axes: LayoutAxes,
-    /// The alignment of the finished layout.
+    /// The alignment of the _resulting_ layout. This does not effect the line
+    /// layouting itself, but rather how the finished layout will be positioned
+    /// in a parent layout.
     pub align: LayoutAlign,
-    /// Whether the layout that is to be created will be nested in a parent
-    /// container.
-    pub nested: bool,
+    /// Whether this layouting process is the root page-building process.
+    pub root: bool,
 }
 
 /// A collection of layout spaces.
@@ -89,17 +83,17 @@ pub type LayoutSpaces = Vec<LayoutSpace>;
 /// The space into which content is laid out.
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub struct LayoutSpace {
-    /// The maximum size of the box to layout in.
+    /// The maximum size of the rectangle to layout into.
     pub size: Size,
     /// Padding that should be respected on each side.
     pub padding: Margins,
     /// Whether to expand the size of the resulting layout to the full size of
-    /// this space or to shrink them to fit the content.
+    /// this space or to shrink it to fit the content.
     pub expansion: LayoutExpansion,
 }
 
 impl LayoutSpace {
-    /// The offset from the origin to the start of content, that is,
+    /// The offset from the origin to the start of content, i.e.
     /// `(padding.left, padding.top)`.
     pub fn start(&self) -> Size {
         Size::new(self.padding.left, self.padding.top)
@@ -110,9 +104,10 @@ impl LayoutSpace {
         self.size.unpadded(self.padding)
     }
 
-    /// A layout space without padding and size reduced by the padding.
-    pub fn usable_space(&self) -> LayoutSpace {
-        LayoutSpace {
+    /// The inner layout space with size reduced by the padding, zero padding of
+    /// its own and no layout expansion.
+    pub fn inner(&self) -> Self {
+        Self {
             size: self.usable(),
             padding: Margins::ZERO,
             expansion: LayoutExpansion::new(false, false),
@@ -123,34 +118,33 @@ impl LayoutSpace {
 /// A sequence of layouting commands.
 pub type Commands<'a> = Vec<Command<'a>>;
 
-/// Commands issued to the layouting engine by trees.
+/// Commands executable by the layouting engine.
 #[derive(Debug, Clone)]
 pub enum Command<'a> {
     /// Layout the given tree in the current context (i.e. not nested). The
     /// content of the tree is not laid out into a separate box and then added,
-    /// but simply laid out flat in the active layouting process.
+    /// but simply laid out flatly in the active layouting process.
     ///
     /// This has the effect that the content fits nicely into the active line
     /// layouting, enabling functions to e.g. change the style of some piece of
-    /// text while keeping it integrated in the current paragraph.
+    /// text while keeping it part of the current paragraph.
     LayoutSyntaxTree(&'a SyntaxTree),
 
-    /// Add a already computed layout.
+    /// Add a finished layout.
     Add(BoxLayout),
     /// Add multiple layouts, one after another. This is equivalent to multiple
-    /// [Add](Command::Add) commands.
+    /// `Add` commands.
     AddMultiple(MultiLayout),
 
-    /// Add spacing of given [kind](super::SpacingKind) along the primary or
-    /// secondary axis. The spacing kind defines how the spacing interacts with
-    /// surrounding spacing.
+    /// Add spacing of the given kind along the primary or secondary axis. The
+    /// kind defines how the spacing interacts with surrounding spacing.
     AddSpacing(f64, SpacingKind, GenAxis),
 
     /// Start a new line.
     BreakLine,
     /// Start a new paragraph.
     BreakParagraph,
-    /// Start a new page, which will exist in the finished layout even if it
+    /// Start a new page, which will be part of the finished layout even if it
     /// stays empty (since the page break is a _hard_ space break).
     BreakPage,
 
@@ -162,6 +156,6 @@ pub enum Command<'a> {
     /// Update the alignment for future boxes added to this layouting process.
     SetAlignment(LayoutAlign),
     /// Update the layouting axes along which future boxes will be laid
-    /// out. This finishes the current line.
+    /// out. This ends the current line.
     SetAxes(LayoutAxes),
 }