Update/improve generated documentation

haskell/free-foil/src/Control/Monad/Foil/TH/MkFoilData.hs

@@ -6,6 +6,7 @@
 module Control.Monad.Foil.TH.MkFoilData where
 
 import           Language.Haskell.TH
+import Language.Haskell.TH.Syntax (addModFinalizer)
 
 import qualified Control.Monad.Foil.Internal as Foil
 import Control.Monad.Foil.TH.Util
@@ -27,6 +28,10 @@ mkFoilData termT nameT scopeT patternT = do
   let foilTermCons = map (toTermCon termTVars n l) termCons
 
   patternD <- mkFoilPattern nameT patternT
+  addModFinalizer $ putDoc (DeclDoc foilTermT)
+    ("/Generated/ with '" ++ show 'mkFoilData ++ "'. A scope-safe version of '" ++ show termT ++ "'.")
+  addModFinalizer $ putDoc (DeclDoc foilScopeT)
+    ("/Generated/ with '" ++ show 'mkFoilData ++ "'. A scope-safe version of '" ++ show scopeT ++ "'.")
   return $
     [ DataD [] foilTermT (termTVars ++ [KindedTV n BndrReq (PromotedT ''Foil.S)]) Nothing foilTermCons []
     , DataD [] foilScopeT (scopeTVars ++ [KindedTV n BndrReq (PromotedT ''Foil.S)]) Nothing foilScopeCons []
@@ -74,6 +79,8 @@ mkFoilPattern nameT patternT = do
 
   foilPatternCons <- mapM (toPatternCon patternTVars n) patternCons
 
+  addModFinalizer $ putDoc (DeclDoc foilPatternT)
+    ("/Generated/ with '" ++ show 'mkFoilPattern ++ "'. A scope-safe version of '" ++ show patternT ++ "'.")
   return
     [ DataD [] foilPatternT (patternTVars ++ [KindedTV n BndrReq (PromotedT ''Foil.S), KindedTV l BndrReq (PromotedT ''Foil.S)]) Nothing foilPatternCons []
     ]
@@ -90,6 +97,7 @@ mkFoilPattern nameT patternT = do
     toPatternCon tvars n (NormalC conName params) = do
       (lastScopeName, foilParams) <- toPatternConParams 1 n params
       let foilConName = mkName ("Foil" ++ nameBase conName)
+      addModFinalizer $ putDoc (DeclDoc foilConName) ("Corresponds to '" ++ show conName ++ "'.")
       return (GadtC [foilConName] foilParams (PeelConT foilPatternT (map (VarT . tvarName) tvars ++ [VarT n, VarT lastScopeName])))
       where
         -- | Process type parameters of a pattern,

haskell/free-foil/src/Control/Monad/Foil/TH/MkFromFoil.hs

@@ -57,12 +57,12 @@ mkFromFoil termT nameT scopeT patternT = do
           -> $rtype
         |]
 
-  addModFinalizer $ putDoc (DeclDoc fromFoilTermT)
-    "Convert a scope-safe term into a raw term."
-  addModFinalizer $ putDoc (DeclDoc fromFoilPatternT)
-    "Convert a scope-safe pattern into a raw pattern."
-  addModFinalizer $ putDoc (DeclDoc fromFoilScopedT)
-    "Convert a scope-safe scoped term into a raw scoped term."
+  addModFinalizer $ putDoc (DeclDoc fromFoilTermT) $
+    "/Generated/ with '" ++ show 'mkFromFoil ++ "'. Convert a scope-safe term into a raw term."
+  addModFinalizer $ putDoc (DeclDoc fromFoilPatternT) $
+    "/Generated/ with '" ++ show 'mkFromFoil ++ "'. Convert a scope-safe pattern into a raw pattern."
+  addModFinalizer $ putDoc (DeclDoc fromFoilScopedT) $
+    "/Generated/ with '" ++ show 'mkFromFoil ++ "'. Convert a scope-safe scoped term into a raw scoped term."
 
   return
     [ fromFoilTermSignature
@@ -252,8 +252,8 @@ mkFromFoilPattern nameT patternT = do
           -> $(return (PeelConT patternT patternParams))
         |]
 
-  addModFinalizer $ putDoc (DeclDoc fromFoilPatternT)
-    "Convert a scope-safe pattern into a raw pattern."
+  addModFinalizer $ putDoc (DeclDoc fromFoilPatternT) $
+    "/Generated/ with '" ++ show 'mkFromFoilPattern ++ "'. Convert a scope-safe pattern into a raw pattern."
 
   return
     [ fromFoilPatternSignature

haskell/free-foil/src/Control/Monad/Foil/TH/MkToFoil.hs

@@ -55,8 +55,10 @@ mkExtendScopeFoilPattern nameT patternT = do
   idfun <- [e| id |]
   extendScopeFun <- [e| Foil.extendScope |]
 
-  addModFinalizer $ putDoc (DeclDoc extendScopePatternFunName)
-    "Extend a scope with the names bound by the given pattern.\nThis is a more flexible version of 'Control.Monad.Foil.extendScope'."
+  addModFinalizer $ putDoc (DeclDoc extendScopePatternFunName) $ unlines
+    [ "/Generated/ with '" ++ show 'mkExtendScopeFoilPattern ++ "'."
+    , "Extend a scope with the names bound by the given pattern."
+    , "This is a more flexible version of '" ++ show 'Foil.extendScope ++ "'." ]
 
   return
     [ extendScopePatternSignature
@@ -144,8 +146,10 @@ mkWithRefreshedFoilPattern nameT patternT = do
   withRefreshedFun <- [e| Foil.withRefreshed |]
   extendScopeFun <- [e| Foil.extendScope |]
 
-  addModFinalizer $ putDoc (DeclDoc withRefreshedFoilPatternFunName)
-    "Refresh (if needed) bound variables introduced in a pattern.\nThis is a more flexible version of 'Control.Monad.Foil.withRefreshed'."
+  addModFinalizer $ putDoc (DeclDoc withRefreshedFoilPatternFunName) $ unlines
+    [ "/Generated/ with '" ++ show 'mkWithRefreshedFoilPattern ++ "'."
+    , "Refresh (if needed) bound variables introduced in a pattern."
+    , "This is a more flexible version of '" ++ show 'Foil.withRefreshed ++ "'." ]
 
   return
     [ withRefreshedFoilPatternSignature
@@ -258,12 +262,12 @@ mkToFoilTerm termT nameT scopeT patternT = do
           -> $rtype
         |]
 
-  addModFinalizer $ putDoc (DeclDoc toFoilTermT)
-    "Convert a raw term into a scope-safe term."
-  addModFinalizer $ putDoc (DeclDoc toFoilPatternT)
-    "Convert a raw pattern into a scope-safe pattern."
-  addModFinalizer $ putDoc (DeclDoc toFoilScopedT)
-    "Convert a raw scoped term into a scope-safe scoped term."
+  addModFinalizer $ putDoc (DeclDoc toFoilTermT) $
+    "/Generated/ with '" ++ show 'mkToFoilTerm ++ "'. Convert a raw term into a scope-safe term."
+  addModFinalizer $ putDoc (DeclDoc toFoilPatternT) $
+    "/Generated/ with '" ++ show 'mkToFoilTerm ++ "'. Convert a raw pattern into a scope-safe pattern."
+  addModFinalizer $ putDoc (DeclDoc toFoilScopedT) $
+    "/Generated/ with '" ++ show 'mkToFoilTerm ++ "'. Convert a raw scoped term into a scope-safe scoped term."
 
   return
     [ toFoilTermSignature
@@ -479,8 +483,8 @@ mkToFoilPattern nameT patternT = do
           -> $rtype
         |]
 
-  addModFinalizer $ putDoc (DeclDoc toFoilPatternT)
-    "Convert a raw pattern into a scope-safe pattern."
+  addModFinalizer $ putDoc (DeclDoc toFoilPatternT) $
+    "/Generated/ with '" ++ show 'mkToFoilPattern ++ "'. Convert a raw pattern into a scope-safe pattern."
 
   return
     [ toFoilPatternSignature

haskell/free-foil/src/Control/Monad/Free/Foil/TH/Convert.hs

@@ -61,7 +61,7 @@ mkConvertToSig termT nameT scopeT patternT = do
     [t| $termType -> Either $nameType ($signatureType ($patternType, $scopeType) $termType) |]
 
   addModFinalizer $ putDoc (DeclDoc convertTermToSigT)
-    ("/Generated/ with '" ++ show 'mkConvertToFreeFoil ++ "'. Perform one step of converting '" ++ show termT ++ "', peeling off one node of type '" ++ show signatureT ++ "'.")
+    ("/Generated/ with '" ++ show 'mkConvertToSig ++ "'. Perform one step of converting '" ++ show termT ++ "', peeling off one node of type '" ++ show signatureT ++ "'.")
   return
     [ SigD convertTermToSigT convertTermToSigClausesType
     , FunD convertTermToSigT convertTermToSigClauses
@@ -130,7 +130,7 @@ mkConvertFromSig termT nameT scopeT patternT = do
     [t| $signatureType ($patternType, $scopeType) $termType -> $termType |]
 
   addModFinalizer $ putDoc (DeclDoc convertTermFromSigT)
-    ("/Generated/ with '" ++ show 'mkConvertToFreeFoil ++ "'. Perform one step of converting '" ++ show termT ++ "', peeling off one node of type '" ++ show signatureT ++ "'.")
+    ("/Generated/ with '" ++ show 'mkConvertFromSig ++ "'. Perform one step of converting '" ++ show termT ++ "', peeling off one node of type '" ++ show signatureT ++ "'.")
   return
     [ SigD convertTermFromSigT convertTermFromSigClausesType
     , FunD convertTermFromSigT convertTermFromSigClauses