From ef43a584230273ef4074103b0c59e489da35c858 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <alcinnz@lavabit.com>
Date: Thu, 10 Nov 2022 21:28:48 +1300
Subject: [PATCH] Finish documenting fonts!

---
 Data/Text/Glyphize/Font.hs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/Data/Text/Glyphize/Font.hs b/Data/Text/Glyphize/Font.hs
index 6f6d1bd..6b4c391 100644
--- a/Data/Text/Glyphize/Font.hs
+++ b/Data/Text/Glyphize/Font.hs
@@ -723,6 +723,7 @@ foreign import ccall "hb_font_get_v_extents" hb_font_get_v_extents
 --- Configurable fonts
 ------
 
+-- | Allows configuring properties on a `Font` when creating it.
 data FontOptions = FontOptions {
     optionPPEm :: Maybe (Word, Word),
     -- ^ Sets the horizontal and vertical pixels-per-em (ppem) of the newly-created `Font`.
@@ -757,12 +758,14 @@ data FontOptions = FontOptions {
     optionVarNamedInstance :: Maybe Word
     -- ^ Sets design coords of a font from a named instance index.
 }
+-- | `FontOptions` which has no effect on the newly-created `Font`.
 defaultFontOptions = FontOptions {
     optionPPEm = Nothing, optionPtEm = Nothing, optionScale = Nothing,
     optionFace = Nothing, optionParent = Nothing,-- optionSynthSlant = Nothing,
     optionVariations = [], optionVarCoordsDesign = [], optionVarCoordsNormalized = [],
     optionVarNamedInstance = Nothing
 }
+-- | Internal utility to apply the given `FontOptions` to the given `Font`.
 _setFontOptions font opts = do
     case optionPPEm opts of
         Just (x, y) -> hb_font_set_ppem font x y
@@ -811,6 +814,7 @@ foreign import ccall "hb_font_set_var_coords_normalized"
 foreign import ccall "hb_font_set_var_named_instance" hb_font_set_var_named_instance ::
     Font_ -> Word -> IO ()
 
+-- | Variant of `createFont` which applies the given `FontOptions`.
 createFontWithOptions :: FontOptions -> Face -> Font
 createFontWithOptions opts fce = unsafePerformIO $ do
     font <- withForeignPtr fce $ hb_font_create
@@ -818,6 +822,7 @@ createFontWithOptions opts fce = unsafePerformIO $ do
     hb_font_make_immutable font
     newForeignPtr hb_font_destroy font
 
+-- | Variant of `ftCreateFont` which applies the given `FontOptions`.
 ftCreateFontWithOptions :: FontOptions -> FT_Face -> Font
 ftCreateFontWithOptions opts fce = unsafePerformIO $ do
     font <- hb_ft_font_create_referenced fce
@@ -825,13 +830,23 @@ ftCreateFontWithOptions opts fce = unsafePerformIO $ do
     hb_font_make_immutable font
     newForeignPtr hb_font_destroy font
 
+-- | Variant of createSubFont which applies the given `FontOptions`.
+createSubFontWithOptions :: FontOptions -> Font -> Font
+createSubFontWithOptions opts font = unsafePerformIO $ do
+    font <- withForeignPtr font $ hb_font_create_sub_font
+    _setFontOptions font opts
+    hb_font_make_immutable font
+    newForeignPtr hb_font_destroy font
+
 ------
 --- Internal
 ------
 
+-- | Harfbuzz's equivalent to the ByteString type.
 type Blob = ForeignPtr Blob'
 data Blob'
 type Blob_ = Ptr Blob'
+-- | Convert from a ByteString to Harfbuzz's equivalent.
 bs2blob :: ByteString -> IO Blob
 bs2blob (BS bytes len) = do
     blob <- withForeignPtr bytes $ \bytes' ->
@@ -842,6 +857,7 @@ foreign import ccall "hb_blob_create" hb_blob_create ::
 hb_MEMORY_MODE_DUPLICATE = 0
 foreign import ccall "&hb_blob_destroy" hb_blob_destroy :: FunPtr (Blob_ -> IO ())
 
+-- | Convert to a ByteString from Harfbuzz's equivalent.
 blob2bs :: Blob_ -> ByteString
 blob2bs blob = unsafePerformIO $ alloca $ \length' -> do
     dat <- hb_blob_get_data blob length'
@@ -852,21 +868,27 @@ blob2bs blob = unsafePerformIO $ alloca $ \length' -> do
 foreign import ccall "hb_blob_get_data" hb_blob_get_data :: Blob_ -> Ptr Word -> IO CString
 foreign import ccall "hb_blob_destroy" hb_blob_destroy' :: Blob_ -> IO ()
 
+-- | Internal utility for defining trivial language bindings unwrapping `Face` foreign pointers.
 faceFunc :: (Face_ -> a) -> (Face -> a)
 faceFunc cb fce = unsafePerformIO $ withForeignPtr fce $ return . cb
 
+-- | Internal utility for defining trivial language bindings unwrapping `Font` foreign pointers.
 fontFunc :: (Font_ -> a) -> (Font -> a)
 fontFunc cb fnt = unsafePerformIO $ withForeignPtr fnt $ return . cb
 
+-- | Internal utility for exposing Harfbuzz functions that populate a bitset.
+-- Converts the populated bitset to a Haskell lazy linked-list.
 faceCollectFunc :: (Face_ -> Set_ -> IO ()) -> (Face -> [Word32])
 faceCollectFunc cb fce = unsafePerformIO $ withForeignPtr fce $ \fce' -> do
     set <- createSet
     withForeignPtr set $ cb fce'
     set2list set
 
+-- | A Harfbuzz bitset.
 data Set'
 type Set = ForeignPtr Set'
 type Set_ = Ptr Set'
+-- | Creates a Harfbuzz bitset wrapping it in a foreignpointer.
 createSet :: IO Set
 createSet = do
     ret <- hb_set_create
@@ -874,6 +896,7 @@ createSet = do
 foreign import ccall "hb_set_create" hb_set_create :: IO Set_
 foreign import ccall "&hb_set_destroy" hb_set_destroy :: FunPtr (Set_ -> IO ())
 
+-- | Lazily retrieves the next codepoint in a bitset.
 setNext :: Set -> Word32 -> Maybe Word32
 setNext set iter = unsafePerformIO $ withForeignPtr set $ \set' -> alloca $ \iter' -> do
     poke iter' iter
@@ -883,6 +906,7 @@ setNext set iter = unsafePerformIO $ withForeignPtr set $ \set' -> alloca $ \ite
     else return Nothing
 foreign import ccall "hb_set_next" hb_set_next :: Set_ -> Ptr Word32 -> IO Bool
 
+-- | Converts a Harfbuzz bitset into a lazy linkedlist.
 set2list :: Set -> IO [Word32]
 set2list set = return $ inner maxBound
   where
-- 
2.30.2