Add some module descriptions.

default.nix

@@ -6,6 +6,7 @@ in rec
   {
     # Build with nix-build -A <attr>
     binaries = nixpkgs.haskellPackages.slab;
+    haddock = nixpkgs.haskellPackages.slab.doc;
 
     # A shell to try out our binaries
     # Run with nix-shell default.nix -A shell

scripts/serve-haddock.sh

@@ -0,0 +1,7 @@
+#! /usr/bin/env nix-shell
+#! nix-shell -i bash -p busybox
+
+HADDOCK_DIR=$(nix-build -A haddock ./default.nix --no-out-link)
+
+echo "Visit http://127.0.0.1:9000/"
+httpd -f -p 9000 -h "${HADDOCK_DIR}/share/doc/slab-0.0.2.0/html/"

slab.cabal

@@ -11,7 +11,7 @@ synopsis:           A programmable markup language to generate HTML
 description:
     Slab is an alternative syntax for writing HTML, plus some programming
     language features (often found in templating languages, like conditionals
-    and loops).
+    and loops). You can visit the project homepage at <https://slab-lang.org>.
 category:           text
 
 source-repository head

src/Slab/Build.hs

@@ -1,3 +1,13 @@
+-- |
+-- Module      : Slab.Build
+-- Description : Build Slab templates to HTML
+--
+-- @Slab.Build@ provides types and functions to easily build Slab templates.
+-- There are mostly two ways to build templates: by writing the resulting HTML
+-- to files, or by writing them to an @STM@-based store.
+--
+-- Writing to disk is used by the @slab watch@ command. Writing to the @STM@
+-- store is used by the @slab serve@ command.
 module Slab.Build
   ( buildDir
   , buildFile

src/Slab/Error.hs

@@ -1,3 +1,10 @@
+-- |
+-- Module      : Slab.Error
+-- Description : Errors that the different Slab stages can produce
+--
+-- @Slab.Error@ provides a data type to represent all the errors emitted by
+-- Slab. It also provides helper functions to report errors in a human-readable
+-- way.
 module Slab.Error
   ( Error (..)
   , unwrap

src/Slab/Evaluate.hs

@@ -1,5 +1,19 @@
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Slab.Evaluate
+-- Description : Evaluate an AST (to a non-reducible AST)
+--
+-- @Slab.Evaluate@ implements the evaluation stage of Slab, following both the
+-- parsing and pre-processing stages. This is responsible of reducing for
+-- instance @1 + 2@ to @3@, or transforming a loop construct to an actual list
+-- of HTML blocks.
+--
+-- Evaluation works on an abstract syntax tree (defined in "Slab.Syntax") and
+-- currently reuses the sames types for its result.
+--
+-- The stage following evaluation is "Slab.Execute", responsible of running
+-- external commands.
 module Slab.Evaluate
   ( evaluateFile
   , evaluate

src/Slab/Execute.hs

@@ -1,6 +1,16 @@
 {-# LANGUAGE MultiWayIf #-}
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Slab.Execute
+-- Description : Run external commands referenced by an AST
+--
+-- @Slab.Execute@ implements the execution stage of Slab, i.e. running external
+-- commands (for instance referenced by the @run@ syntax). This is done after
+-- the evaluation stage (implemented in "Slab.Evaluate").
+--
+-- After execution, the resulting blocks can be rendered to HTML by
+-- "Slab.Render".
 module Slab.Execute
   ( executeFile
   , execute

src/Slab/Generate/Haskell.hs

@@ -1,3 +1,11 @@
+-- |
+-- Module      : Slab.Generate.Haskell
+-- Description : Translate from the Slab syntax to Haskell
+--
+-- @Slab.Generate.Haskell@ is an attempt to translate Slab to Haskell. This
+-- could make it possible to use Slab within Haskell projects without needing
+-- to interpret Slab templates at runtime. If this proves useful, other
+-- languages could also be supported.
 module Slab.Generate.Haskell
   ( renderHs
   ) where

src/Slab/Parse.hs

@@ -1,5 +1,13 @@
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Slab.Parse
+-- Description : Parse the concrete Slab syntax to an AST
+--
+-- @Slab.Parse@ provides parsers to read text and construct an abstract syntax
+-- tree, as represented by "Slab.Syntax".
+--
+-- Parsers are written using the @megaparsec@ library.
 module Slab.Parse
   ( parseFile
   , parseFileE

src/Slab/PreProcess.hs

@@ -1,6 +1,13 @@
 {-# LANGUAGE MultiWayIf #-}
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Slab.PreProcess
+-- Description : Parse and process included and imported files
+--
+-- @Slab.PreProcess@ recursively parses files, following includes and imports.
+-- This is also responsible of reading JSON files referenced in the expression
+-- language.
 module Slab.PreProcess
   ( Context (..)
   , preprocessFile

src/Slab/Render.hs

@@ -1,3 +1,9 @@
+-- |
+-- Module      : Slab.Render
+-- Description : Render an AST to HTML
+--
+-- @Slab.Render@ transforms an evaluated syntax tree to HTML. In practice this
+-- can be @blaze-html@'s @Html@, or @Text@ and lazy @ByteString@.
 module Slab.Render
   ( prettyHtmls
   , renderHtmls

src/Slab/Report.hs

@@ -1,3 +1,9 @@
+-- |
+-- Module      : Slab.Report
+-- Description : Report information about Slab templates (mostly empty for now)
+--
+-- This module serves as a way to explore new Slab features, e.g. creating a
+-- module system, or analyzing a growing HTML code base to help refactor it.
 module Slab.Report
   ( run
   ) where
@@ -28,6 +34,7 @@ isPage _ = False
 
 --------------------------------------------------------------------------------
 -- Similar to Build.buildDir and buildFile, but don't render HTML to disk.
+-- TODO Move this code to (and combine it with) with @Slab.Build@.
 
 buildDir :: FilePath -> IO [Module]
 buildDir srcDir = do

src/Slab/Serve.hs

@@ -2,6 +2,12 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE NoImplicitPrelude #-}
 
+-- |
+-- Module      : Slab.Serve
+-- Description : Run a development server to preview Slab templates
+--
+-- @Slab.Serve@ watches a set of Slab templates, continuously rebuilding them
+-- as they change, and runs a web server to serve them.
 module Slab.Serve
   ( run
   ) where

src/Slab/Syntax.hs

@@ -1,5 +1,11 @@
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Slab.Syntax
+-- Description : The abstract syntax used by Slab
+--
+-- @Slab.Syntax@ provides data types to represent the syntax used by the Slab
+-- language. It also provides small helpers functions to operate on the syntax.
 module Slab.Syntax
   ( Block (..)
   , isDoctype

src/Slab/Watch.hs

@@ -1,3 +1,9 @@
+-- |
+-- Module      : Slab.Watch
+-- Description : Continuously build a set of Slab templates
+--
+-- @Slab.Watch@ watches a set of Slab templates, continuously rebuilding them
+-- as they change.
 module Slab.Watch
   ( run
   ) where