From 24d072018c8fcbe47a73a941edcb91edb7a4edb2 Mon Sep 17 00:00:00 2001
From: Troels Henriksen <athas@sigkill.dk>
Date: Mon, 25 Jan 2021 15:48:47 +0100
Subject: [PATCH] More and fixed Haddocks.

---
 src/Futhark/Actions.hs                           |  1 +
 src/Futhark/Analysis/PrimExp.hs                  | 12 ++++++------
 src/Futhark/CLI/Literate.hs                      |  1 +
 src/Futhark/CLI/Multicore.hs                     |  2 ++
 src/Futhark/CodeGen/Backends/GenericC/CLI.hs     |  3 +++
 src/Futhark/CodeGen/Backends/GenericC/Server.hs  |  3 +++
 src/Futhark/CodeGen/Backends/MulticoreC.hs       |  1 +
 src/Futhark/CodeGen/Backends/PyOpenCL.hs         |  3 ++-
 src/Futhark/CodeGen/Backends/SequentialPython.hs |  2 ++
 src/Futhark/CodeGen/ImpCode.hs                   |  2 ++
 src/Futhark/CodeGen/ImpGen.hs                    |  2 +-
 src/Futhark/CodeGen/ImpGen/CUDA.hs               |  2 ++
 src/Futhark/CodeGen/ImpGen/Kernels/SegRed.hs     |  2 +-
 src/Futhark/CodeGen/ImpGen/Kernels/SegScan.hs    |  3 +++
 src/Futhark/CodeGen/ImpGen/Multicore.hs          |  1 +
 src/Futhark/CodeGen/ImpGen/Multicore/Base.hs     |  4 ++--
 src/Futhark/CodeGen/ImpGen/Multicore/SegMap.hs   |  1 +
 src/Futhark/CodeGen/ImpGen/OpenCL.hs             |  2 ++
 src/Futhark/IR/Prop/Types.hs                     |  2 +-
 src/Futhark/Internalise/LiftLambdas.hs           |  2 ++
 src/Futhark/Script.hs                            |  8 +++++++-
 src/Futhark/Test.hs                              |  1 +
 src/Language/Futhark/TypeChecker/Match.hs        |  2 ++
 23 files changed, 49 insertions(+), 13 deletions(-)

diff --git a/src/Futhark/Actions.hs b/src/Futhark/Actions.hs
index ffa6d8e49c..aab4cee4cf 100644
--- a/src/Futhark/Actions.hs
+++ b/src/Futhark/Actions.hs
@@ -77,6 +77,7 @@ kernelImpCodeGenAction =
       actionProcedure = liftIO . putStrLn . pretty . snd <=< ImpGenKernels.compileProgOpenCL
     }
 
+-- | Convert the program to CPU multicore ImpCode and print it to stdout.
 multicoreImpCodeGenAction :: Action MCMem
 multicoreImpCodeGenAction =
   Action
diff --git a/src/Futhark/Analysis/PrimExp.hs b/src/Futhark/Analysis/PrimExp.hs
index 63c3099f5e..22f7675196 100644
--- a/src/Futhark/Analysis/PrimExp.hs
+++ b/src/Futhark/Analysis/PrimExp.hs
@@ -147,19 +147,19 @@ instance Traversable (TPrimExp t) where
 instance FreeIn v => FreeIn (TPrimExp t v) where
   freeIn' = freeIn' . untyped
 
--- | This expression is of type 'Int8'.
+-- | This expression is of type t'Int8'.
 isInt8 :: PrimExp v -> TPrimExp Int8 v
 isInt8 = TPrimExp
 
--- | This expression is of type 'Int16'.
+-- | This expression is of type t'Int16'.
 isInt16 :: PrimExp v -> TPrimExp Int16 v
 isInt16 = TPrimExp
 
--- | This expression is of type 'Int32'.
+-- | This expression is of type t'Int32'.
 isInt32 :: PrimExp v -> TPrimExp Int32 v
 isInt32 = TPrimExp
 
--- | This expression is of type 'Int64'.
+-- | This expression is of type t'Int64'.
 isInt64 :: PrimExp v -> TPrimExp Int64 v
 isInt64 = TPrimExp
 
@@ -167,11 +167,11 @@ isInt64 = TPrimExp
 isBool :: PrimExp v -> TPrimExp Bool v
 isBool = TPrimExp
 
--- | This expression is of type 'Float'.
+-- | This expression is of type t'Float'.
 isF32 :: PrimExp v -> TPrimExp Float v
 isF32 = TPrimExp
 
--- | This expression is of type 'Double'.
+-- | This expression is of type t'Double'.
 isF64 :: PrimExp v -> TPrimExp Double v
 isF64 = TPrimExp
 
diff --git a/src/Futhark/CLI/Literate.hs b/src/Futhark/CLI/Literate.hs
index a1ffc476b3..330fc0e7f8 100644
--- a/src/Futhark/CLI/Literate.hs
+++ b/src/Futhark/CLI/Literate.hs
@@ -1,6 +1,7 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE OverloadedStrings #-}
 
+-- | @futhark literate@
 module Futhark.CLI.Literate (main) where
 
 import Control.Monad.Except
diff --git a/src/Futhark/CLI/Multicore.hs b/src/Futhark/CLI/Multicore.hs
index e367621f32..201e8db9fd 100644
--- a/src/Futhark/CLI/Multicore.hs
+++ b/src/Futhark/CLI/Multicore.hs
@@ -1,11 +1,13 @@
 {-# LANGUAGE FlexibleContexts #-}
 
+-- | @futhark multicore@
 module Futhark.CLI.Multicore (main) where
 
 import Futhark.Actions (compileMulticoreAction)
 import Futhark.Compiler.CLI
 import Futhark.Passes (multicorePipeline)
 
+-- | Run @futhark multicore@.
 main :: String -> [String] -> IO ()
 main = compilerMain
   ()
diff --git a/src/Futhark/CodeGen/Backends/GenericC/CLI.hs b/src/Futhark/CodeGen/Backends/GenericC/CLI.hs
index 5d2405a37b..4be7a1c8cc 100644
--- a/src/Futhark/CodeGen/Backends/GenericC/CLI.hs
+++ b/src/Futhark/CodeGen/Backends/GenericC/CLI.hs
@@ -6,6 +6,7 @@
 {-# LANGUAGE Trustworthy #-}
 {-# LANGUAGE TupleSections #-}
 
+-- | Code generation for standalone executables.
 module Futhark.CodeGen.Backends.GenericC.CLI
   ( cliDefs,
   )
@@ -362,6 +363,8 @@ cliEntryPoint fname (Function _ _ _ _ results args) =
       )
 
 {-# NOINLINE cliDefs #-}
+
+-- | Generate Futhark standalone executable code.
 cliDefs :: [Option] -> Functions a -> [C.Definition]
 cliDefs options (Functions funs) =
   let values_h = $(embedStringFile "rts/c/values.h")
diff --git a/src/Futhark/CodeGen/Backends/GenericC/Server.hs b/src/Futhark/CodeGen/Backends/GenericC/Server.hs
index c8c99a3a25..52b671a831 100644
--- a/src/Futhark/CodeGen/Backends/GenericC/Server.hs
+++ b/src/Futhark/CodeGen/Backends/GenericC/Server.hs
@@ -6,6 +6,7 @@
 {-# LANGUAGE Trustworthy #-}
 {-# LANGUAGE TupleSections #-}
 
+-- | Code generation for server executables.
 module Futhark.CodeGen.Backends.GenericC.Server
   ( serverDefs,
   )
@@ -205,6 +206,8 @@ mkBoilerplate funs =
    in (type_defs ++ entry_defs, type_inits, entry_inits)
 
 {-# NOINLINE serverDefs #-}
+
+-- | Generate Futhark server executable code.
 serverDefs :: [Option] -> Functions a -> [C.Definition]
 serverDefs options funs =
   let server_h = $(embedStringFile "rts/c/server.h")
diff --git a/src/Futhark/CodeGen/Backends/MulticoreC.hs b/src/Futhark/CodeGen/Backends/MulticoreC.hs
index 546a2dd30b..35d74a7e97 100644
--- a/src/Futhark/CodeGen/Backends/MulticoreC.hs
+++ b/src/Futhark/CodeGen/Backends/MulticoreC.hs
@@ -27,6 +27,7 @@ import Futhark.MonadFreshNames
 import qualified Language.C.Quote.OpenCL as C
 import qualified Language.C.Syntax as C
 
+-- | Compile the program to ImpCode with multicore operations.
 compileProg ::
   MonadFreshNames m =>
   Prog MCMem ->
diff --git a/src/Futhark/CodeGen/Backends/PyOpenCL.hs b/src/Futhark/CodeGen/Backends/PyOpenCL.hs
index 1244e3965d..7377182601 100644
--- a/src/Futhark/CodeGen/Backends/PyOpenCL.hs
+++ b/src/Futhark/CodeGen/Backends/PyOpenCL.hs
@@ -1,6 +1,7 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE TupleSections #-}
 
+-- | Code generation for Python with OpenCL.
 module Futhark.CodeGen.Backends.PyOpenCL
   ( compileProg,
   )
@@ -18,7 +19,7 @@ import Futhark.IR.KernelsMem (KernelsMem, Prog)
 import Futhark.MonadFreshNames
 import Futhark.Util (zEncodeString)
 
---maybe pass the config file rather than multiple arguments
+-- | Compile the program to Python with calls to OpenCL.
 compileProg ::
   MonadFreshNames m =>
   Py.CompilerMode ->
diff --git a/src/Futhark/CodeGen/Backends/SequentialPython.hs b/src/Futhark/CodeGen/Backends/SequentialPython.hs
index e6bfd41193..47ba78284b 100644
--- a/src/Futhark/CodeGen/Backends/SequentialPython.hs
+++ b/src/Futhark/CodeGen/Backends/SequentialPython.hs
@@ -1,3 +1,4 @@
+-- | Code generation for sequential Python.
 module Futhark.CodeGen.Backends.SequentialPython
   ( compileProg,
   )
@@ -11,6 +12,7 @@ import qualified Futhark.CodeGen.ImpGen.Sequential as ImpGen
 import Futhark.IR.SeqMem
 import Futhark.MonadFreshNames
 
+-- | Compile the program to Python.
 compileProg ::
   MonadFreshNames m =>
   GenericPython.CompilerMode ->
diff --git a/src/Futhark/CodeGen/ImpCode.hs b/src/Futhark/CodeGen/ImpCode.hs
index c556adb660..b02901cb24 100644
--- a/src/Futhark/CodeGen/ImpCode.hs
+++ b/src/Futhark/CodeGen/ImpCode.hs
@@ -599,6 +599,8 @@ instance Traversable Code where
   traverse _ (DebugPrint s v) =
     pure $ DebugPrint s v
 
+-- | The names declared with 'DeclareMem', 'DeclareScalar', and
+-- 'DeclareArray' in the given code.
 declaredIn :: Code a -> Names
 declaredIn (DeclareMem name _) = oneName name
 declaredIn (DeclareScalar name _ _) = oneName name
diff --git a/src/Futhark/CodeGen/ImpGen.hs b/src/Futhark/CodeGen/ImpGen.hs
index d93447b9de..8ce7f71bfd 100644
--- a/src/Futhark/CodeGen/ImpGen.hs
+++ b/src/Futhark/CodeGen/ImpGen.hs
@@ -1567,7 +1567,7 @@ compileAlloc pat _ _ =
   error $ "compileAlloc: Invalid pattern: " ++ pretty pat
 
 -- | The number of bytes needed to represent the array in a
--- straightforward contiguous format, as an 'Int64' expression.
+-- straightforward contiguous format, as an t'Int64' expression.
 typeSize :: Type -> Count Bytes (Imp.TExp Int64)
 typeSize t =
   Imp.bytes $
diff --git a/src/Futhark/CodeGen/ImpGen/CUDA.hs b/src/Futhark/CodeGen/ImpGen/CUDA.hs
index 2be4d8675c..78b0fbefc4 100644
--- a/src/Futhark/CodeGen/ImpGen/CUDA.hs
+++ b/src/Futhark/CodeGen/ImpGen/CUDA.hs
@@ -1,3 +1,4 @@
+-- | Code generation for ImpCode with CUDA kernels.
 module Futhark.CodeGen.ImpGen.CUDA
   ( compileProg,
     Warnings,
@@ -11,5 +12,6 @@ import Futhark.CodeGen.ImpGen.Kernels.ToOpenCL
 import Futhark.IR.KernelsMem
 import Futhark.MonadFreshNames
 
+-- | Compile the program to ImpCode with CUDA kernels.
 compileProg :: MonadFreshNames m => Prog KernelsMem -> m (Warnings, Program)
 compileProg prog = second kernelsToCUDA <$> compileProgCUDA prog
diff --git a/src/Futhark/CodeGen/ImpGen/Kernels/SegRed.hs b/src/Futhark/CodeGen/ImpGen/Kernels/SegRed.hs
index 3d23173d95..4413e8d13e 100644
--- a/src/Futhark/CodeGen/ImpGen/Kernels/SegRed.hs
+++ b/src/Futhark/CodeGen/ImpGen/Kernels/SegRed.hs
@@ -71,7 +71,7 @@ maxNumOps = 10
 -- | Code generation for the body of the SegRed, taking a continuation
 -- for saving the results of the body.  The results should be
 -- represented as a pairing of a t'SubExp' along with a list of
--- indexes into that 'SubExp' for reading the result.
+-- indexes into that t'SubExp' for reading the result.
 type DoSegBody = ([(SubExp, [Imp.TExp Int64])] -> InKernelGen ()) -> InKernelGen ()
 
 -- | Compile 'SegRed' instance to host-level code with calls to
diff --git a/src/Futhark/CodeGen/ImpGen/Kernels/SegScan.hs b/src/Futhark/CodeGen/ImpGen/Kernels/SegScan.hs
index b6e0639064..70ac7bb678 100644
--- a/src/Futhark/CodeGen/ImpGen/Kernels/SegScan.hs
+++ b/src/Futhark/CodeGen/ImpGen/Kernels/SegScan.hs
@@ -1,3 +1,6 @@
+-- | Code generation for 'SegScan'.  Dispatches to either a
+-- single-pass or two-pass implementation, depending on the nature of
+-- the scan and the chosen abckend.
 module Futhark.CodeGen.ImpGen.Kernels.SegScan (compileSegScan) where
 
 import qualified Futhark.CodeGen.ImpCode.Kernels as Imp
diff --git a/src/Futhark/CodeGen/ImpGen/Multicore.hs b/src/Futhark/CodeGen/ImpGen/Multicore.hs
index 8ff87a2e12..e5269de253 100644
--- a/src/Futhark/CodeGen/ImpGen/Multicore.hs
+++ b/src/Futhark/CodeGen/ImpGen/Multicore.hs
@@ -1,6 +1,7 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE TypeFamilies #-}
 
+-- | Code generation for ImpCode with multicore operations.
 module Futhark.CodeGen.ImpGen.Multicore
   ( Futhark.CodeGen.ImpGen.Multicore.compileProg,
     Warnings,
diff --git a/src/Futhark/CodeGen/ImpGen/Multicore/Base.hs b/src/Futhark/CodeGen/ImpGen/Multicore/Base.hs
index 292912bcea..f7f4c532a6 100644
--- a/src/Futhark/CodeGen/ImpGen/Multicore/Base.hs
+++ b/src/Futhark/CodeGen/ImpGen/Multicore/Base.hs
@@ -170,8 +170,8 @@ decideScheduling code =
     else Imp.Dynamic
 
 -- | Try to extract invariant allocations.  If we assume that the
--- given 'Code' is the body of a 'SegOp', then it is always safe to
--- move the immediate allocations to the prebody.
+-- given 'Imp.Code' is the body of a 'SegOp', then it is always safe
+-- to move the immediate allocations to the prebody.
 extractAllocations :: Imp.Code -> (Imp.Code, Imp.Code)
 extractAllocations segop_code = f segop_code
   where
diff --git a/src/Futhark/CodeGen/ImpGen/Multicore/SegMap.hs b/src/Futhark/CodeGen/ImpGen/Multicore/SegMap.hs
index 849c12bc38..4736b36a74 100644
--- a/src/Futhark/CodeGen/ImpGen/Multicore/SegMap.hs
+++ b/src/Futhark/CodeGen/ImpGen/Multicore/SegMap.hs
@@ -1,3 +1,4 @@
+-- | Multicore code generation for 'SegMap'.
 module Futhark.CodeGen.ImpGen.Multicore.SegMap
   ( compileSegMap,
   )
diff --git a/src/Futhark/CodeGen/ImpGen/OpenCL.hs b/src/Futhark/CodeGen/ImpGen/OpenCL.hs
index cc0892dd1f..37cfa9243e 100644
--- a/src/Futhark/CodeGen/ImpGen/OpenCL.hs
+++ b/src/Futhark/CodeGen/ImpGen/OpenCL.hs
@@ -1,3 +1,4 @@
+-- | Code generation for ImpCode with OpenCL kernels.
 module Futhark.CodeGen.ImpGen.OpenCL
   ( compileProg,
     Warnings,
@@ -11,5 +12,6 @@ import Futhark.CodeGen.ImpGen.Kernels.ToOpenCL
 import Futhark.IR.KernelsMem
 import Futhark.MonadFreshNames
 
+-- | Compile the program to ImpCode with OpenCL kernels.
 compileProg :: MonadFreshNames m => Prog KernelsMem -> m (Warnings, OpenCL.Program)
 compileProg prog = second kernelsToOpenCL <$> compileProgOpenCL prog
diff --git a/src/Futhark/IR/Prop/Types.hs b/src/Futhark/IR/Prop/Types.hs
index 54f1edaab9..7661ea5114 100644
--- a/src/Futhark/IR/Prop/Types.hs
+++ b/src/Futhark/IR/Prop/Types.hs
@@ -417,7 +417,7 @@ shapeContext =
     ext (Free _) = Nothing
 
 -- | If all dimensions of the given 'ExtShape' are statically known,
--- change to the corresponding 'Shape'.
+-- change to the corresponding t'Shape'.
 hasStaticShape :: TypeBase ExtShape u -> Maybe (TypeBase Shape u)
 hasStaticShape (Prim bt) = Just $ Prim bt
 hasStaticShape (Mem space) = Just $ Mem space
diff --git a/src/Futhark/Internalise/LiftLambdas.hs b/src/Futhark/Internalise/LiftLambdas.hs
index f67e01e9a1..7370e0d31c 100644
--- a/src/Futhark/Internalise/LiftLambdas.hs
+++ b/src/Futhark/Internalise/LiftLambdas.hs
@@ -168,6 +168,8 @@ transformValBind vb = do
   addValBind $ vb {valBindBody = e}
 
 {-# NOINLINE transformProg #-}
+
+-- | Perform the transformation.
 transformProg :: MonadFreshNames m => [ValBind] -> m [ValBind]
 transformProg vbinds =
   modifyNameSource $ \namesrc ->
diff --git a/src/Futhark/Script.hs b/src/Futhark/Script.hs
index 2755f327b4..a5144665e8 100644
--- a/src/Futhark/Script.hs
+++ b/src/Futhark/Script.hs
@@ -3,7 +3,7 @@
 
 -- | FutharkScript is a (tiny) subset of Futhark used to write small
 -- expressions that are evaluated by server executables.  The @futhark
--- script@ command is the main user.
+-- literate@ command is the main user.
 module Futhark.Script
   ( -- * Server
     ScriptServer,
@@ -65,6 +65,10 @@ withScriptServer prog options f = withServer prog options $ \server -> do
   counter <- newIORef 0
   f $ ScriptServer server counter
 
+-- | A FutharkScript expression.  This is a simple AST that might not
+-- correspond exactly to what the user wrote (e.g. no parentheses or
+-- source locations).  This is fine for small expressions, which is
+-- all this is meant for.
 data Exp
   = Call EntryName [Exp]
   | Const PrimValue
@@ -162,6 +166,7 @@ inParens sep = between (lexeme sep "(") (lexeme sep ")")
 inBraces :: Parser () -> Parser a -> Parser a
 inBraces sep = between (lexeme sep "{") (lexeme sep "}")
 
+-- | Parse a FutharkScript expression.
 parseExp :: Parser () -> Parser Exp
 parseExp sep =
   choice
@@ -270,6 +275,7 @@ valueToExp (V.ValueRecord fs) =
 valueToExp (V.ValueTuple fs) =
   Tuple $ map valueToExp fs
 
+-- | Evaluate a FutharkScript expression relative to some running server.
 evalExp :: (MonadError T.Text m, MonadIO m) => ScriptServer -> Exp -> m ExpValue
 evalExp (ScriptServer server counter) top_level_e = do
   vars <- liftIO $ newIORef []
diff --git a/src/Futhark/Test.hs b/src/Futhark/Test.hs
index b19b9fcfab..6f38b3fea6 100644
--- a/src/Futhark/Test.hs
+++ b/src/Futhark/Test.hs
@@ -787,6 +787,7 @@ runProgram futhark runner extra_options prog entry input = do
   input' <- getValuesBS futhark dir input
   liftIO $ readProcessWithExitCode to_run to_run_args $ BS.toStrict input'
 
+-- | Read the given variables from a running server.
 readResults ::
   (MonadIO m, MonadError T.Text m) =>
   Server ->
diff --git a/src/Language/Futhark/TypeChecker/Match.hs b/src/Language/Futhark/TypeChecker/Match.hs
index 81884ac1f3..9cebaade01 100644
--- a/src/Language/Futhark/TypeChecker/Match.hs
+++ b/src/Language/Futhark/TypeChecker/Match.hs
@@ -162,6 +162,8 @@ findUnmatched [] _ = [[]]
 findUnmatched _ _ = []
 
 {-# NOINLINE unmatched #-}
+
+-- | Find the unmatched cases.
 unmatched :: [Pattern] -> [Match]
 unmatched orig_ps =
   -- The algorithm may find duplicate example, which we filter away