From 0b971321040ca633a863e7d5f012e33b5edc7c30 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Mon, 10 Apr 2023 09:01:34 +1200
Subject: [PATCH] Document Graphics.Layout.Grid.CSS

---
 Graphics/Layout/Grid/CSS.hs | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/Graphics/Layout/Grid/CSS.hs b/Graphics/Layout/Grid/CSS.hs
index 89311d7..af19394 100644
--- a/Graphics/Layout/Grid/CSS.hs
+++ b/Graphics/Layout/Grid/CSS.hs
@@ -13,25 +13,43 @@ import Graphics.Layout.Box
 import Graphics.Layout.Grid
 import Graphics.Layout
 
+-- | Parsed CSS Grid properties
 data CSSGrid = CSSGrid {
+    -- | Parsed CSS grid-auto-columns
     autoColumns :: Unitted,
+    -- | Parsed grid-auto-flow
     autoFlow :: Axis,
+    -- | Whether grid-auto-flow: dense was specified.
     autoFlowDense :: Bool,
+    -- | Parsed CSS grid-auto-rows
     autoRows :: Unitted,
+    -- | Parsed CSS grid-template-areas
     templateAreas :: [[Text]],
+    -- | Parsed CSS grid-template-columns
     templateColumns :: [([Text], Unitted)],
+    -- | Parsed CSS grid-template-rows
     templateRows :: [([Text], Unitted)],
+    -- | Parsed CSS row-gap & column-gap
     cssGap :: Size Unitted Unitted,
+    -- | Parsed CSS justify-items & align-items
     alignItems :: Size Alignment Alignment
 }
+-- | A grid axis.
 data Axis = Row | Col deriving Eq
+-- | Parsed CSS grid item properties.
 data CSSCell = CSSCell {
+    -- | Parsed CSS grid-column-start
     columnStart :: Placement,
+    -- | Parsed CSS grid-column-end
     columnEnd :: Placement,
+    -- | Parsed CSS grid-row-start
     rowStart :: Placement,
+    -- | Parsed CSS grid-row-end
     rowEnd :: Placement,
+    -- | Parsed CSS align-self & justify-self
     alignSelf :: Size (Maybe Alignment) (Maybe Alignment)
 }
+-- | Identifies a cell in the CSS grid.
 data Placement = Autoplace | Named Text | Numbered Int (Maybe Text) |
         Span Int (Maybe Text)
 
@@ -50,7 +68,7 @@ instance PropertyParser CSSGrid where
     inherit _ = temp
 
     longhand _ s "grid-auto-columns" toks | Just x <- parseFR toks = Just s {autoColumns=x}
-    longhand _ s "grid-auto-rows" toks | Just x <- parseFR toks = Just s {autoColumns = x}
+    longhand _ s "grid-auto-rows" toks | Just x <- parseFR toks = Just s { autoRows = x }
 
     longhand _ self "grid-auto-flow" [Ident "row"] = Just self {
         autoFlow = Row, autoFlowDense = False
@@ -204,11 +222,14 @@ instance PropertyParser CSSCell where
 
     longhand _ _ _ _ = Nothing
 
+-- | Parse a length or FR unit.
 parseFR [Dimension _ x "fr"] = Just (n2f x,"fr")
 parseFR toks = parseLength toks
+-- | Parse a length or FR unit, including extended keywords.
 parseFR' [Dimension _ x "fr"] = Just (n2f x,"fr")
 parseFR' toks = parseLength' toks
 
+-- | Parse an identifier for a grid cell.
 placement [Ident "auto"] = Just $ Autoplace
 placement [Ident x] = Just $ Named x
 placement [Number _ (NVInteger x)] = Just $ Numbered (fromEnum x) Nothing
@@ -222,10 +243,12 @@ placement [Ident "span", Ident y, Number _ (NVInteger x)]
     | x > 0 = Just $ Span (fromEnum x) (Just y)
 placement _ = Nothing
 
+-- | Parse grid-template-*
 parseTemplate [Ident "none"] = Just []
 parseTemplate [Ident "initial"] = Just []
 parseTemplate toks | (tracks@(_:_), []) <- parseTrack toks = Just tracks
 parseTemplate _ = Nothing
+-- | Parse an individual track specified by grid-template-*
 parseTrack (LeftSquareBracket:toks)
     | Just (names', toks') <- parseNames toks,
         ((names,size):cells,toks) <- parseTrack toks' = ((names' ++ names,size):cells,toks)
@@ -236,6 +259,7 @@ parseTrack (Function "repeat":Number _ (NVInteger x):Comma:toks)
     | x > 0, (tracks@(_:_), RightParen:toks') <- parseTrack toks =
         (concat $ replicate (fromEnum x) tracks, toks')
 parseTrack toks = ([], toks)
+-- | (UNUSED) Parse a subgrid specified by grid-template-*
 parseSubgrid (LeftSquareBracket:toks)
     | Just (names', toks') <- parseNames toks, (names,toks'') <- parseSubgrid toks' =
         (names' : names, toks')
@@ -243,11 +267,13 @@ parseSubgrid (Function "repeat":Number _ (NVInteger x):Comma:toks)
     | x > 0, (names@(_:_), RightParen:toks') <- parseSubgrid toks =
         (concat $ replicate (fromEnum x) names, toks')
 parseSubgrid toks = ([], toks)
+-- | Parse a track's names.
 parseNames (Ident x:toks)
     | Just (names,toks') <- parseNames toks = Just (x:names,toks')
 parseNames (RightSquareBracket:toks) = Just ([], toks)
 parseNames _ = Nothing
 
+-- | Desugar grid properties to a grid layout.
 finalizeGrid :: PropertyParser x => CSSGrid -> Font' ->
     [CSSCell] -> [LayoutItem Length Length x] -> LayoutItem Length Length x
 finalizeGrid self@CSSGrid {
-- 
2.30.2