From 2277b56b06f74bdcfa6128b102ab974f61f0e161 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Wed, 1 Apr 2020 09:55:14 +1300
Subject: [PATCH] Write reference documentation.

---
 src/Data/CSS/Preprocessor/Conditions.hs      |  2 ++
 src/Data/CSS/Preprocessor/Conditions/Expr.hs |  1 +
 src/Data/CSS/Style.hs                        | 12 +++++++++++-
 src/Data/CSS/Style/Cascade.hs                |  7 +++++++
 4 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/Data/CSS/Preprocessor/Conditions.hs b/src/Data/CSS/Preprocessor/Conditions.hs
index 61c514a..b04ab2d 100644
--- a/src/Data/CSS/Preprocessor/Conditions.hs
+++ b/src/Data/CSS/Preprocessor/Conditions.hs
@@ -115,10 +115,12 @@ parseAtImport self src toks
         (addRule' self $ External cond uri, toks')
 parseAtImport self _ toks = (self, skipAtRule toks)
 
+-- | Returns `@import` URLs that need to be imported.
 extractImports :: (Text -> Query.Datum) -> (Token -> Query.Datum) -> ConditionalStyles p -> [URI]
 extractImports vars evalToken self =
     [uri | External cond uri <- rules self, Query.eval vars evalToken cond]
 
+-- | Substitutes external values in for `@import` rules.
 resolveImports :: ConditionalStyles p -> [(URI, ConditionalStyles p)] -> ConditionalStyles p
 resolveImports self responses = self {rules = map resolveImport $ rules self}
     where
diff --git a/src/Data/CSS/Preprocessor/Conditions/Expr.hs b/src/Data/CSS/Preprocessor/Conditions/Expr.hs
index 5b2a4eb..d45ef72 100644
--- a/src/Data/CSS/Preprocessor/Conditions/Expr.hs
+++ b/src/Data/CSS/Preprocessor/Conditions/Expr.hs
@@ -55,6 +55,7 @@ pushOp toks op b ops = parse' toks ((op, b):ops)
 --------
 ---- Shunting Yard Evaluator
 --------
+-- | Dynamic types for evaluating media queries.
 data Datum = B Bool | N Float | Ratio Float Float deriving Eq
 
 eval :: (Text -> Datum) -> (Token -> Datum) -> Expr -> Bool
diff --git a/src/Data/CSS/Style.hs b/src/Data/CSS/Style.hs
index de85895..ce42eec 100644
--- a/src/Data/CSS/Style.hs
+++ b/src/Data/CSS/Style.hs
@@ -21,16 +21,22 @@ import Data.HashMap.Strict (HashMap, lookupDefault, fromList)
 import Data.Text (isPrefixOf)
 import Data.List (elemIndex)
 
+-- | A parsed CSS stylesheet from which you can query styles to match an element.
 type QueryableStyleSheet parser = QueryableStyleSheet' (ImportanceSplitter (
         PropertyExpander parser (OrderedRuleStore (InterpretedRuleStore StyleIndex))
     )) parser
 
+-- | More generic version of `QueryableStyleSheet`.
 data QueryableStyleSheet' store parser = QueryableStyleSheet' {
+    -- | Internal datastructure for efficient style lookup.
     store :: store,
+    -- | The "PropertyParser" to use for property syntax validation.
     parser :: parser,
+    -- | Whether author, useragent, or user styles are currently being parsed.
     priority :: Int -- author vs user agent vs user styles
 }
 
+-- | Constructs an empty QueryableStyleSheet'.
 queryableStyleSheet :: PropertyParser p => QueryableStyleSheet p
 queryableStyleSheet = QueryableStyleSheet' {store = new, parser = temp, priority = 0}
 
@@ -41,14 +47,17 @@ instance (RuleStore s, PropertyParser p) => StyleSheet (QueryableStyleSheet' s p
         }
 
 --- Reexpose cascade methods
+-- | Looks up style rules matching the specified element, grouped by psuedoelement.
 queryRules :: (PropertyParser p, RuleStore s) =>
     QueryableStyleSheet' s p -> Element -> HashMap Text [StyleRule']
 queryRules (QueryableStyleSheet' store' _ _) = Cascade.query store'
 
+-- | Selects used property values from the given style rules,
+-- & populates into a new `PropertyParser` inheriting from the one given.
 cascade' :: PropertyParser p => [StyleRule'] -> Props -> p -> p
 cascade' = Cascade.cascade
 
---- Facade for trivial cases
+-- | Facade over `queryRules` & `cascade'` for simple cases you don't care about psuedoelements.
 cascade :: PropertyParser p => QueryableStyleSheet p -> Element -> Props -> p -> p
 cascade self el = cascade' $ lookupDefault [] "" $ queryRules self el
 
@@ -71,6 +80,7 @@ expandProperties _ [] = []
 --------
 ---- var()
 --------
+-- | `PropertyParser` that lowers var() calls before forwarding to another.
 data VarParser a = VarParser {vars :: Props, innerParser :: a}
 
 instance PropertyParser p => PropertyParser (VarParser p) where
diff --git a/src/Data/CSS/Style/Cascade.hs b/src/Data/CSS/Style/Cascade.hs
index 79c7039..d410946 100644
--- a/src/Data/CSS/Style/Cascade.hs
+++ b/src/Data/CSS/Style/Cascade.hs
@@ -12,22 +12,29 @@ import Data.CSS.Syntax.Tokens
 import Data.HashMap.Strict
 import Data.Text (unpack, pack, isPrefixOf)
 
+-- | Defines how to parse CSS properties into an output "style" format.
 class PropertyParser a where
+    -- | Default styles.
     temp :: a
+    -- | Creates a style inherited from a parent style.
     inherit :: a -> a
     inherit = id
 
+    -- | Expand a shorthand property into longhand properties.
     shorthand :: a -> Text -> [Token] -> [(Text, [Token])]
     shorthand self key value | Just _ <- longhand self self key value = [(key, value)]
         | otherwise = []
     -- longhand parent self name value
     longhand :: a -> a -> Text -> [Token] -> Maybe a
 
+    -- | Retrieve stored variables, optional.
     getVars :: a -> Props
     getVars _ = []
+    -- | Save variable values, optional.
     setVars :: Props -> a -> a
     setVars _ = id
 
+-- | Gather properties into a hashmap.
 data TrivialPropertyParser = TrivialPropertyParser (HashMap String [Token])
 instance PropertyParser TrivialPropertyParser where
     temp = TrivialPropertyParser empty
-- 
2.30.2