From d87a046b2dba99d6142a85af6a126f9a9396b563 Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Tue, 20 Dec 2022 12:00:03 +1300
Subject: [PATCH] Document FcLangSet language bindings.

---
 Graphics/Text/Font/Choose/LangSet.hs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/Graphics/Text/Font/Choose/LangSet.hs b/Graphics/Text/Font/Choose/LangSet.hs
index 9e1a608..39e823d 100644
--- a/Graphics/Text/Font/Choose/LangSet.hs
+++ b/Graphics/Text/Font/Choose/LangSet.hs
@@ -15,35 +15,58 @@ import Control.Exception (bracket)
 import Control.Monad (forM)
 import System.IO.Unsafe (unsafePerformIO)
 
+-- | An `LangSet` is a set of language names (each of which include language and
+-- an optional territory). They are used when selecting fonts to indicate which
+-- languages the fonts need to support. Each font is marked, using language
+-- orthography information built into fontconfig, with the set of supported languages.
 type LangSet = Set String
 
+-- | Returns a string set of the default languages according to the environment
+-- variables on the system. This function looks for them in order of FC_LANG,
+-- LC_ALL, LC_CTYPE and LANG then. If there are no valid values in those
+-- environment variables, "en" will be set as fallback.
 defaultLangs :: IO LangSet
 defaultLangs = thawStrSet =<< fcGetDefaultLangs
 foreign import ccall "FcGetDefaultLangs" fcGetDefaultLangs :: IO StrSet_
 
+-- | Returns a string set of all known languages.
 langs :: LangSet
 langs = unsafePerformIO $ thawStrSet_ $ fcGetLangs
 foreign import ccall "FcGetLangs" fcGetLangs :: IO StrSet_
 
 data LangResult = SameLang | DifferentTerritory | DifferentLang
     deriving (Enum, Eq, Read, Show)
+-- | `langSetCompare` compares language coverage for ls_a and ls_b.
+-- If they share any language and territory pair, returns `SameLang`.
+-- If they share a language but differ in which territory that language is for,
+-- this function returns `DifferentTerritory`.
+-- If they share no languages in common, this function returns `DifferentLang`.
 langSetCompare :: LangSet -> LangSet -> LangResult
 langSetCompare a b = unsafePerformIO $ withLangSet a $ \a' -> withLangSet b $ \b' ->
     (toEnum <$> fcLangSetCompare a' b')
 foreign import ccall "FcLangSetCompare" fcLangSetCompare ::
     LangSet_ -> LangSet_ -> IO Int
 
+-- | `langSetContains` returns FcTrue if ls_a contains every language in ls_b.
+-- ls_a will 'contain' a language from ls_b if ls_a has exactly the language,
+-- or either the language or ls_a has no territory.
 langSetContains :: LangSet -> LangSet -> Bool
 langSetContains a b = unsafePerformIO $ withLangSet a $ \a' -> withLangSet b $
     fcLangSetContains a'
 foreign import ccall "FcLangSetContains" fcLangSetContains ::
     LangSet_ -> LangSet_ -> IO Bool
 
+-- | FcLangSetHasLang checks whether ls supports lang.
+-- If ls has a matching language and territory pair, this function returns
+-- `SameLang`. If ls has a matching language but differs in which territory
+-- that language is for, this function returns `DifferentTerritory`. If ls has
+-- no matching language, this function returns `DifferentLang`.
 langSetHasLang :: LangSet -> String -> LangResult
 langSetHasLang a b = unsafePerformIO $ withLangSet a $ \a' -> withCString b $ \b' ->
     (toEnum <$> fcLangSetHasLang a' b')
 foreign import ccall "FcLangSetHasLang" fcLangSetHasLang :: LangSet_ -> CString -> IO Int
 
+-- | Returns a string to make lang suitable on FontConfig.
 langNormalize :: String -> String
 langNormalize "" = ""
 langNormalize lang = unsafePerformIO $ withCString lang (peekCString_ . fcLangNormalize)
@@ -53,6 +76,7 @@ peekCString_ str' = do
     free str'
     return str
 
+-- | Returns the FcCharMap for a language.
 langCharSet :: String -> CharSet
 langCharSet lang = unsafePerformIO $
     withCString lang (thawCharSet . throwNull . fcLangGetCharSet)
-- 
2.30.2