From dbefdc068d0644a778f12cc661e87a4086429505 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Fri, 7 Jun 2024 16:08:15 +1200
Subject: [PATCH] Document modules.

---
 lib/Graphics/Text/Font/Choose.hs                  | 1 +
 lib/Graphics/Text/Font/Choose/CharSet.hs          | 2 +-
 lib/Graphics/Text/Font/Choose/Config.hs           | 1 +
 lib/Graphics/Text/Font/Choose/Config/Accessors.hs | 2 ++
 lib/Graphics/Text/Font/Choose/FontSet.hs          | 1 +
 lib/Graphics/Text/Font/Choose/Internal/FFI.hs     | 2 ++
 lib/Graphics/Text/Font/Choose/LangSet.hs          | 1 +
 lib/Graphics/Text/Font/Choose/ObjectSet.hs        | 1 +
 lib/Graphics/Text/Font/Choose/Pattern.hs          | 2 ++
 lib/Graphics/Text/Font/Choose/Range.hs            | 1 +
 lib/Graphics/Text/Font/Choose/Result.hs           | 1 +
 lib/Graphics/Text/Font/Choose/StrSet.hs           | 1 +
 lib/Graphics/Text/Font/Choose/Value.hs            | 1 +
 lib/Graphics/Text/Font/Choose/Weight.hs           | 1 +
 14 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/lib/Graphics/Text/Font/Choose.hs b/lib/Graphics/Text/Font/Choose.hs
index 953c738..11862cd 100644
--- a/lib/Graphics/Text/Font/Choose.hs
+++ b/lib/Graphics/Text/Font/Choose.hs
@@ -1,3 +1,4 @@
+-- | Query installed fonts from FontConfig.
 module Graphics.Text.Font.Choose(
         module Graphics.Text.Font.Choose.Config.Accessors, Config', fini, version,
         initLoadConfig, initLoadConfigAndFonts, initFonts, reinit, bringUptoDate,
diff --git a/lib/Graphics/Text/Font/Choose/CharSet.hs b/lib/Graphics/Text/Font/Choose/CharSet.hs
index e18f3ac..6c6137f 100644
--- a/lib/Graphics/Text/Font/Choose/CharSet.hs
+++ b/lib/Graphics/Text/Font/Choose/CharSet.hs
@@ -1,8 +1,8 @@
+-- | Process sets of unicode characters, possibly parsed from CSS.
 module Graphics.Text.Font.Choose.CharSet(
         CharSet, ord, chr, module IntSet, parseCharSet, CharSet'(..), validCharSet'
     ) where
 
-import Data.IntSet (IntSet, union)
 import Data.IntSet as IntSet
 
 import Data.Char (isHexDigit, ord, chr)
diff --git a/lib/Graphics/Text/Font/Choose/Config.hs b/lib/Graphics/Text/Font/Choose/Config.hs
index 7483e4e..70f1105 100644
--- a/lib/Graphics/Text/Font/Choose/Config.hs
+++ b/lib/Graphics/Text/Font/Choose/Config.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE CApiFFI #-}
+-- | Load system fonts configuration.
 module Graphics.Text.Font.Choose.Config(Config', fini, version,
         initLoadConfig, initLoadConfigAndFonts, initFonts, reinit, bringUptoDate,
         -- For the sake of Graphics.Font.Choose.Config.Accessors
diff --git a/lib/Graphics/Text/Font/Choose/Config/Accessors.hs b/lib/Graphics/Text/Font/Choose/Config/Accessors.hs
index d24f60b..65c50f3 100644
--- a/lib/Graphics/Text/Font/Choose/Config/Accessors.hs
+++ b/lib/Graphics/Text/Font/Choose/Config/Accessors.hs
@@ -1,4 +1,6 @@
 {-# LANGUAGE CApiFFI #-}
+-- | APIs for retrieving configuration
+-- This is seperate from Graphics.Text.Font.Choose.Config to avoid cyclic dependencies.
 module Graphics.Text.Font.Choose.Config.Accessors(
         configCreate, setCurrent, current, uptodate, home, enableHome, buildFonts,
         configDirs, fontDirs, configFiles, cacheDirs, fonts, rescanInterval,
diff --git a/lib/Graphics/Text/Font/Choose/FontSet.hs b/lib/Graphics/Text/Font/Choose/FontSet.hs
index 4cfb1d1..be25492 100644
--- a/lib/Graphics/Text/Font/Choose/FontSet.hs
+++ b/lib/Graphics/Text/Font/Choose/FontSet.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE CApiFFI, OverloadedStrings #-}
+-- | A set of fonts to query, or resulting from a query.
 module Graphics.Text.Font.Choose.FontSet(
         FontSet, validFontSet, fontSetList, fontSetMatch, fontSetSort, FontFaceParser(..)
     ) where
diff --git a/lib/Graphics/Text/Font/Choose/Internal/FFI.hs b/lib/Graphics/Text/Font/Choose/Internal/FFI.hs
index 836c913..7d554d0 100644
--- a/lib/Graphics/Text/Font/Choose/Internal/FFI.hs
+++ b/lib/Graphics/Text/Font/Choose/Internal/FFI.hs
@@ -1,3 +1,5 @@
+-- | Utilities for writing language bindings transferring complex parameters.
+-- Encoding & decoding parameters via MessagePack.
 module Graphics.Text.Font.Choose.Internal.FFI(
         unpackWithErr, withMessageIO, withMessage, fromMessage, fromMessage0,
         fromMessageIO0, withCString', peekCString', withForeignPtr'
diff --git a/lib/Graphics/Text/Font/Choose/LangSet.hs b/lib/Graphics/Text/Font/Choose/LangSet.hs
index 7270a28..1550c0b 100644
--- a/lib/Graphics/Text/Font/Choose/LangSet.hs
+++ b/lib/Graphics/Text/Font/Choose/LangSet.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE CApiFFI #-}
+-- | Languages supported by different fonts.
 module Graphics.Text.Font.Choose.LangSet(
         LangSet, LangSet'(..), module S, LangComparison(..), validLangSet, validLangSet',
         cmp, has, defaultLangs, langs, normalize, langCharSet) where
diff --git a/lib/Graphics/Text/Font/Choose/ObjectSet.hs b/lib/Graphics/Text/Font/Choose/ObjectSet.hs
index fd8a27b..122fb9a 100644
--- a/lib/Graphics/Text/Font/Choose/ObjectSet.hs
+++ b/lib/Graphics/Text/Font/Choose/ObjectSet.hs
@@ -1,3 +1,4 @@
+-- | Which properties of a font do we want to read?
 module Graphics.Text.Font.Choose.ObjectSet(ObjectSet) where
 
 type ObjectSet = [String]
diff --git a/lib/Graphics/Text/Font/Choose/Pattern.hs b/lib/Graphics/Text/Font/Choose/Pattern.hs
index 72a839b..9e65c6a 100644
--- a/lib/Graphics/Text/Font/Choose/Pattern.hs
+++ b/lib/Graphics/Text/Font/Choose/Pattern.hs
@@ -1,5 +1,7 @@
 {-# LANGUAGE DeriveGeneric, CApiFFI #-}
 {-# LANGUAGE OverloadedStrings #-}
+-- | Dynamically-typed datastructure describing a font, whether resolved or a query.
+-- Can be parsed from CSS.
 module Graphics.Text.Font.Choose.Pattern(Pattern, Pattern'(..), module M, Binding(..),
         setValue, setValues, getValue, getValues, equalSubset, defaultSubstitute,
         nameParse, nameUnparse, nameFormat, validPattern, validPattern',
diff --git a/lib/Graphics/Text/Font/Choose/Range.hs b/lib/Graphics/Text/Font/Choose/Range.hs
index 55a7ea1..4e72137 100644
--- a/lib/Graphics/Text/Font/Choose/Range.hs
+++ b/lib/Graphics/Text/Font/Choose/Range.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE DeriveGeneric #-}
+-- | A range between 2 values.
 module Graphics.Text.Font.Choose.Range(Range(..), iRange, validRange) where
 
 import Data.MessagePack (MessagePack(..), Object(..))
diff --git a/lib/Graphics/Text/Font/Choose/Result.hs b/lib/Graphics/Text/Font/Choose/Result.hs
index c8de008..aae9609 100644
--- a/lib/Graphics/Text/Font/Choose/Result.hs
+++ b/lib/Graphics/Text/Font/Choose/Result.hs
@@ -1,3 +1,4 @@
+-- | Exceptions which can be thrown by FontConfig.
 module Graphics.Text.Font.Choose.Result (FcException(..), throwBool, throwNull, throwString) where
 
 import Foreign.Ptr (Ptr, nullPtr)
diff --git a/lib/Graphics/Text/Font/Choose/StrSet.hs b/lib/Graphics/Text/Font/Choose/StrSet.hs
index 2a192a3..02d1ada 100644
--- a/lib/Graphics/Text/Font/Choose/StrSet.hs
+++ b/lib/Graphics/Text/Font/Choose/StrSet.hs
@@ -1,3 +1,4 @@
+-- | A set of strings to match.
 module Graphics.Text.Font.Choose.StrSet(StrSet(..), module S, validStrSet) where
 
 import Data.Set (Set)
diff --git a/lib/Graphics/Text/Font/Choose/Value.hs b/lib/Graphics/Text/Font/Choose/Value.hs
index 28cd420..f395a3b 100644
--- a/lib/Graphics/Text/Font/Choose/Value.hs
+++ b/lib/Graphics/Text/Font/Choose/Value.hs
@@ -1,5 +1,6 @@
 {-# LANGUAGE TypeSynonymInstances, FlexibleInstances, DeriveGeneric #-}
 {-# LANGUAGE OverloadedStrings #-}
+-- | A dynamic type system for patterns.
 module Graphics.Text.Font.Choose.Value(Value(..), validValue, ToValue(..)) where
 
 import Linear.Matrix (M22)
diff --git a/lib/Graphics/Text/Font/Choose/Weight.hs b/lib/Graphics/Text/Font/Choose/Weight.hs
index bd1ad25..7565311 100644
--- a/lib/Graphics/Text/Font/Choose/Weight.hs
+++ b/lib/Graphics/Text/Font/Choose/Weight.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE CApiFFI #-}
+-- | Convert between OpenType & FontConfig weight scales.
 module Graphics.Text.Font.Choose.Weight(weightFromOpenTypeDouble,
         weightToOpenTypeDouble, weightFromOpenType, weightToOpenType) where
 
-- 
2.30.2