From 05c53db184dbbaf4b8d81470fe20ff545fc9dd8e Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Tue, 11 Apr 2023 15:57:11 +1200
Subject: [PATCH] Reference document flow layout module.

---
 Graphics/Layout/Flow.hs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Graphics/Layout/Flow.hs b/Graphics/Layout/Flow.hs
index 0f95a74..c7dc29f 100644
--- a/Graphics/Layout/Flow.hs
+++ b/Graphics/Layout/Flow.hs
@@ -4,12 +4,14 @@ module Graphics.Layout.Flow(flowMinWidth, flowNatWidth, flowMaxWidth, flowWidth,
 
 import Graphics.Layout.Box as B
 
+-- | Compute the minimum width of a block element with children of the given sizes.
 flowMinWidth :: Double -> PaddedBox a Length -> [PaddedBox b Double] -> Double
 flowMinWidth _ PaddedBox {B.min = Size (Pixels x) _} _ = x
 flowMinWidth parent PaddedBox {B.min = Size (Percent x) _} _ = x * parent
 flowMinWidth parent self@PaddedBox {B.min = Size Preferred _} childs =
     flowNatWidth parent self childs
 flowMinWidth _ _ childs = maximum $ (0:) $ map minWidth childs
+-- | Compute the natural width of a block element with children of the given sizes.
 flowNatWidth :: Double -> PaddedBox a Length -> [PaddedBox b Double] -> Double
 flowNatWidth _ PaddedBox {size = Size (Pixels x) _} _ = x
 flowNatWidth parent PaddedBox {size = Size (Percent x) _} _ = x * parent
@@ -17,6 +19,7 @@ flowNatWidth parent self@PaddedBox {size = Size Min _, B.min = Size x _} childs
     -- Avoid infinite loops!
     | x /= Preferred = flowMinWidth parent self childs
 flowNatWidth parent _ childs = maximum $ (0:) $ map maxWidth childs
+-- | Compute the maximum width of a block element inside the given parent size.
 flowMaxWidth :: PaddedBox a Double -> PaddedBox b Length -> Double
 flowMaxWidth _ PaddedBox {B.max = Size (Pixels x) _} = x
 flowMaxWidth parent PaddedBox {B.max = Size (Percent x) _} = x * (inline $ size parent)
@@ -29,6 +32,8 @@ flowMaxWidth parent self@PaddedBox {B.max = Size Preferred _} =
     flowNatWidth (inline $ size parent) self []
 flowMaxWidth parent self@PaddedBox {B.max = Size Min _} =
     flowMinWidth (inline $ B.min parent) self []
+-- | Compute final block element width based on cached width computations &
+-- parent size.
 flowWidth :: PaddedBox a Double -> PaddedBox b Length -> Double
 flowWidth parent self
     | small > large = small
@@ -41,6 +46,7 @@ flowWidth parent self
     natural = flowNatWidth (inline $ size parent) self []
     large = flowMaxWidth parent self
 
+-- | Compute natural block element height at cached width.
 flowNatHeight :: Double -> PaddedBox Length Double -> [PaddedBox Double Double] -> Double
 flowNatHeight _ PaddedBox {size = Size _ (Pixels y)} _ = y
 flowNatHeight parent PaddedBox {size = Size _ (Percent y)} _ = y * parent
@@ -48,16 +54,19 @@ flowNatHeight _ PaddedBox {size = Size _ Min} childs =
     sum $ map minHeight $ marginCollapse childs
 flowNatHeight _ PaddedBox {size = Size owidth _} childs =
     sum $ map height $ marginCollapse childs
+-- | Compute minimum block height at cached width.
 flowMinHeight :: Double -> PaddedBox Length Double -> Double
 flowMinHeight _ PaddedBox {B.min = Size _ (Pixels y)} = y
 flowMinHeight parent PaddedBox {B.min = Size _ (Percent y)} = y * parent
 flowMinHeight parent self = flowNatHeight parent self []
+-- | Compute maximum block height at cached width.
 flowMaxHeight :: Double -> PaddedBox Length Double -> Double
 flowMaxHeight _ PaddedBox {B.max = Size _ (Pixels y)} = y
 flowMaxHeight parent PaddedBox {B.max = Size _ (Percent y)} = y * parent
 flowMaxHeight parent PaddedBox {B.max = Size _ Auto} = parent
 flowMaxHeight parent self@PaddedBox {B.max = Size _ Preferred} = flowNatHeight parent self []
 flowMaxHeight parent self@PaddedBox {B.max = Size _ Min} = flowMinHeight parent self
+-- | Compute final block height at cached width.
 flowHeight :: PaddedBox Double Double -> PaddedBox Length Double -> Double
 flowHeight parent self
     | small > large = small
@@ -69,9 +78,12 @@ flowHeight parent self
     natural = flowNatHeight (block $ size parent) self []
     large = flowMaxHeight (block $ B.max parent) self
 
+-- | Compute position of all children relative to this block element.
 positionFlow :: [PaddedBox Double Double] -> [Size Double Double]
 positionFlow childs = scanl inner (Size 0 0) $ marginCollapse childs
   where inner (Size x y) self = Size x $ height self
+-- | Compute size given block element in given parent,
+-- & position of given children.
 layoutFlow :: PaddedBox Double Double -> PaddedBox Length Length ->
         [PaddedBox Length Double] ->
         (PaddedBox Double Double, [(Size Double Double, PaddedBox Double Double)])
@@ -114,6 +126,7 @@ layoutFlow parent self childs = (self', zip positions' childs')
         margin = mapY (lowerLength owidth) $ margin child
       }
 
+-- | Removes overlapping margins.
 marginCollapse :: [PaddedBox Double n] -> [PaddedBox Double n]
 marginCollapse (x'@PaddedBox {margin = xm@Border { bottom = x }}:
         y'@PaddedBox {margin = ym@Border { top = y}}:rest)
@@ -121,6 +134,7 @@ marginCollapse (x'@PaddedBox {margin = xm@Border { bottom = x }}:
     | otherwise = x' { margin = xm { bottom = 0 }}:marginCollapse (y':rest)
 marginCollapse rest = rest
 
+-- | Resolves auto paddings or margins to fill given width.
 lowerMargin :: Double -> Double -> Border m Length -> Border m Double
 lowerMargin _ available (Border top' bottom' Auto Auto) =
     Border top' bottom' (available/2) (available/2)
-- 
2.30.2