Writers.GridTable: improve module documentation.

src/Text/Pandoc/Writers/GridTable.hs

@@ -10,7 +10,13 @@ License     : GNU GPL, version 2 or above
 
 Maintainer  : Albert Krewinkel <albert@zeitkraut.de>
 
-Grid representation of pandoc tables.
+Grid representation of pandoc tables. The structures in this module
+allow to describe 'Text.Pandoc.Definition.Table' elements without loss
+of information. However, they are simpler to use when the grid layout of
+a table must be known.
+
+The "grid tables" handled here are conceptually similar to grid tables
+in reStructuredText and Markdown, but are more general.
 -}
 module Text.Pandoc.Writers.GridTable
   ( Table (..)
@@ -97,7 +103,7 @@ data BuilderCell
 fromBuilderCell :: BuilderCell -> GridCell
 fromBuilderCell = \case
   FilledCell c -> c
-  FreeCell -> error "Found an unassigned cell."
+  FreeCell -> error "Found an unassigned cell. Please report this as a bug!"
 
 rowsToPart :: Attr -> [B.Row] -> Part
 rowsToPart attr = \case

src/Text/Pandoc/Writers/Shared.hs

@@ -231,14 +231,15 @@ unsmartify opts = T.concatMap $ \c -> case c of
   '\8216' -> "'"
   _       -> T.singleton c
 
+-- | Writes a grid table.
 gridTable :: (Monad m, HasChars a)
           => WriterOptions
-          -> (WriterOptions -> [Block] -> m (Doc a))
+          -> (WriterOptions -> [Block] -> m (Doc a)) -- ^ format Doc writer
           -> Bool             -- ^ headless
-          -> [Alignment]
-          -> [Double]
-          -> [[Block]]
-          -> [[[Block]]]
+          -> [Alignment]      -- ^ column alignments
+          -> [Double]         -- ^ column widths
+          -> [[Block]]        -- ^ table header row
+          -> [[[Block]]]      -- ^ table body rows
           -> m (Doc a)
 gridTable opts blocksToDoc headless aligns widths headers rows = do
   -- the number of columns will be used in case of even widths