From ce6932f33e98ca078d8f5e712e6f5afd46c99fe2 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Mon, 19 Dec 2022 16:55:11 +1300
Subject: [PATCH] Document FcFontSet language bindings.

---
 Graphics/Text/Font/Choose/FontSet.hs     |  4 ++++
 Graphics/Text/Font/Choose/FontSet/API.hs | 22 ++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/Graphics/Text/Font/Choose/FontSet.hs b/Graphics/Text/Font/Choose/FontSet.hs
index ece57e6..ee9fd73 100644
--- a/Graphics/Text/Font/Choose/FontSet.hs
+++ b/Graphics/Text/Font/Choose/FontSet.hs
@@ -19,6 +19,9 @@ import Graphics.Text.Font.Choose.Range (iRange)
 import Graphics.Text.Font.Choose.CharSet (parseCharSet)
 import Data.List (intercalate)
 
+-- | An `FontSet` contains a list of `Pattern`s.
+-- Internally fontconfig uses this data structure to hold sets of fonts.
+-- Externally, fontconfig returns the results of listing fonts in this format.
 type FontSet = [Pattern]
 
 ------
@@ -73,6 +76,7 @@ thawFontSet_ cb = bracket (throwNull <$> cb) fcFontSetDestroy thawFontSet
 --- CSS Bindings
 ------
 
+-- | `StyleSheet` wrapper to parse @font-face rules.
 data FontFaceParser a = FontFaceParser { cssFonts :: FontSet, cssInner :: a}
 
 parseFontFaceSrc (Function "local":Ident name:RightParen:Comma:rest) =
diff --git a/Graphics/Text/Font/Choose/FontSet/API.hs b/Graphics/Text/Font/Choose/FontSet/API.hs
index 0eaa611..e1d9106 100644
--- a/Graphics/Text/Font/Choose/FontSet/API.hs
+++ b/Graphics/Text/Font/Choose/FontSet/API.hs
@@ -13,11 +13,15 @@ import Foreign.ForeignPtr (withForeignPtr)
 import Foreign.Marshal.Alloc (alloca)
 import System.IO.Unsafe (unsafePerformIO)
 
+-- | Selects fonts matching pattern from sets,
+-- creates patterns from those fonts containing only the objects in object_set
+-- and returns the set of unique such patterns.
 fontSetList :: Config -> [FontSet] -> Pattern -> ObjectSet -> FontSet
 fontSetList config fontss pattern objs = unsafePerformIO $ withForeignPtr config $ \config' ->
     withFontSets fontss $ \fontss' n -> withPattern pattern $ \pattern' ->
         withObjectSet objs $ \objs' ->
             thawFontSet_ $ fcFontSetList config' fontss' n pattern' objs'
+-- | Variant of `fontSetList` operating upon register default `Config`.
 fontSetList' :: [FontSet] -> Pattern -> ObjectSet -> FontSet
 fontSetList' fontss pattern objs = unsafePerformIO $ withFontSets fontss $ \fontss' n ->
     withPattern pattern $ \pattern' -> withObjectSet objs $ \objs' ->
@@ -25,12 +29,18 @@ fontSetList' fontss pattern objs = unsafePerformIO $ withFontSets fontss $ \font
 foreign import ccall "FcFontSetList" fcFontSetList ::
     Config_ -> Ptr FontSet_ -> Int -> Pattern_ -> ObjectSet_ -> IO FontSet_
 
+-- | Finds the font in sets most closely matching pattern
+-- and returns the result of `fontRenderPrepare` for that font and
+-- the provided pattern. This function should be called only after
+-- `configSubstitute` and `defaultSubstitute` have been called for pattern;
+-- otherwise the results will not be correct.
 fontSetMatch :: Config -> [FontSet] -> Pattern -> Maybe Pattern
 fontSetMatch config fontss pattern = unsafePerformIO $ withForeignPtr config $ \config' ->
     withFontSets fontss $ \fontss' n -> withPattern pattern $ \pattern' -> 
         alloca $ \res' -> do
             ret <- fcFontSetMatch config' fontss' n pattern' res'
             throwPtr res' $ thawPattern_ $ pure ret
+-- | Variant of `fontSetMatch` operating upon registered default `Config`.
 fontSetMatch' :: [FontSet] -> Pattern -> Maybe Pattern
 fontSetMatch' fontss pattern = unsafePerformIO $ withFontSets fontss $ \fontss' n ->
     withPattern pattern $ \pattern' -> alloca $ \res' -> do
@@ -39,12 +49,24 @@ fontSetMatch' fontss pattern = unsafePerformIO $ withFontSets fontss $ \fontss'
 foreign import ccall "FcFontSetMatch" fcFontSetMatch ::
     Config_ -> Ptr FontSet_ -> Int -> Pattern_ -> Ptr Int -> IO Pattern_
 
+-- | Returns the list of fonts from sets sorted by closeness to pattern.
+-- If trim is `True`, elements in the list which don't include Unicode coverage
+-- not provided by earlier elements in the list are elided.
+-- The union of Unicode coverage of all of the fonts is returned in csp.
+-- This function should be called only after `configSubstitute` and
+-- `defaultSubstitute` have been called for p;
+-- otherwise the results will not be correct.
+-- The returned FcFontSet references `Pattern` structures which may be shared by
+-- the return value from multiple `fontSort` calls, applications cannot modify
+-- these patterns. Instead, they should be passed, along with pattern to
+-- `fontRenderPrepare` which combines them into a complete pattern.
 fontSetSort :: Config -> [FontSet] -> Pattern -> Bool -> CharSet -> Maybe FontSet
 fontSetSort config fontss pattern trim csp = unsafePerformIO $
     withForeignPtr config $ \config' -> withFontSets fontss $ \fontss' n ->
         withPattern pattern $ \pattern' -> withCharSet csp $ \csp' -> alloca $ \res' -> do
             ret' <- fcFontSetSort config' fontss' n pattern' trim csp' res'
             throwPtr res' $ thawFontSet_ $ pure ret'
+-- | Variant of `fontSetSort` operating upon registered default `Config`.
 fontSetSort' :: [FontSet] -> Pattern -> Bool -> CharSet -> Maybe FontSet
 fontSetSort' fontss pattern trim csp = unsafePerformIO $
     withFontSets fontss $ \fontss' n -> withPattern pattern $ \pattern' ->
-- 
2.30.2