From db049adddd02fe6e204c5b211af8c141dd593d01 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Wed, 12 Apr 2023 12:25:42 +1200
Subject: [PATCH] Reference-document inline layout.

---
 Graphics/Layout/Inline.hs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Graphics/Layout/Inline.hs b/Graphics/Layout/Inline.hs
index 8c83421..11bede7 100644
--- a/Graphics/Layout/Inline.hs
+++ b/Graphics/Layout/Inline.hs
@@ -15,41 +15,57 @@ import Data.Int (Int32)
 import Graphics.Layout.Box (Size(..), CastDouble(..), fromDouble)
 import Graphics.Layout.CSS.Font (Font', hbScale)
 
+-- | Convert from Harfbuzz units to device pixels as a Double
 hbScale' font = (/hbScale font) . fromIntegral
+-- | Convert from Harfbuzz units to device pixels as a Double or Length.
 c font = fromDouble . hbScale' font
 
+-- | Compute minimum width for some richtext.
 inlineMinWidth :: Font' -> Paragraph -> Double
 inlineMinWidth font self = hbScale' font $ width $ layoutPlain' self 0
+-- | Compute minimum width & height for some richtext.
 inlineMin :: (CastDouble x, CastDouble y) => Font' -> Paragraph -> Size x y
 inlineMin font self = Size (c font $ width rect) (c font $ height rect)
     where rect = layoutPlain' self 0
+-- | Compute natural (single-line) width for some richtext.
 inlineNatWidth :: Font' -> Paragraph -> Double
 inlineNatWidth font self = hbScale' font $ width $ layoutPlain' self maxBound
+-- | Compute height for rich text at given width.
 inlineHeight :: Font' -> Double -> Paragraph -> Double
 inlineHeight font width self =
     hbScale' font $ height $ layoutPlain' self $ round (hbScale font * width)
 
+-- | Compute width & height of some richtext at configured width.
 inlineSize :: (CastDouble x, CastDouble y) => Font' -> Paragraph -> Size x y
 inlineSize font self = layoutSize font $ layoutPlain self
+-- | Retrieve children out of some richtext,
+-- associating given userdata with them.
 inlineChildren :: [x] -> Paragraph -> [(x, Fragment)]
 inlineChildren vals self = layoutChildren vals $ layoutPlain self
 
+-- | Retrieve a laid-out paragraph's rect & convert to CatTrap types.
 layoutSize :: (CastDouble x, CastDouble y) => Font' -> ParagraphLayout -> Size x y
 layoutSize font self = Size (c font $ width r) (c font $ height r)
   where r = paragraphRect self
+-- | Retrieve a laid-out paragraph's children & associate with given userdata.
 layoutChildren :: [x] -> ParagraphLayout -> [(x, Fragment)]
 layoutChildren vals self = zip vals $ concat $ map inner $ spanLayouts self
   where inner (SpanLayout y) = y
 
+-- | Layout a paragraph at given width & retrieve resulting rect.
 layoutPlain' :: Paragraph -> Int32 -> Rect Int32
 layoutPlain' (Paragraph a b c d) width =
     paragraphRect $ layoutPlain $ Paragraph a b c d { paragraphMaxWidth = width }
 
+-- | Retrieve the rect for a fragment & convert to CatTrap types.
 fragmentSize :: (CastDouble x, CastDouble y) => Font' -> Fragment -> Size x y
 fragmentSize font self = Size (c font $ width r) (c font $ height r)
     where r = fragmentRect self
+-- | Variant of `fragmentSize` asserting to the typesystem that both fields
+-- of the resulting `Size` are of the same type.
 fragmentSize' :: CastDouble x => Font' -> Fragment -> Size x x
 fragmentSize' = fragmentSize -- Work around for typesystem.
+-- | Retrieve the position of a fragment.
 fragmentPos :: Font' -> (Double, Double) -> Fragment -> (Double, Double)
 fragmentPos font (x, y) self =
         (x + hbScale' font (x_min r), y + hbScale' font (y_min r))
-- 
2.30.2