lua-filters.md: auto-generate docs for more modules

4 files changed, 144 insertions, 46 deletions

diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Format.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Format.hs
index b4397e2bc..0080994a7 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Format.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Format.hs
@@ -26,7 +26,7 @@ documentedModule :: Module PandocError
 documentedModule = Module
   { moduleName = "pandoc.format"
   , moduleDescription = T.unlines
-    [ "Pandoc formats and their extensions."
+    [ "Information about the formats supported by pandoc."
     ]
   , moduleFields = []
   , moduleOperations = []
@@ -37,19 +37,7 @@ documentedModule = Module
 -- | Extension module functions.
 functions :: [DocumentedFunction PandocError]
 functions =
-  [ defun "default_extensions"
-     ### liftPure getDefaultExtensions
-     <#> parameter peekText "string" "format" "format name"
-     =#> functionResult pushExtensions "FormatExtensions"
-           "default extensions enabled for `format`"
-     #? T.unlines
-        [ "Returns the list of default extensions of the given format; this"
-        , "function does not check if the format is supported, it will return"
-        , "a fallback list of extensions even for unknown formats."
-        ]
-     `since` makeVersion [3,0]
-
-  , defun "all_extensions"
+  [ defun "all_extensions"
      ### liftPure getAllExtensions
      <#> parameter peekText "string" "format" "format name"
      =#> functionResult pushExtensions "FormatExtensions"
@@ -62,6 +50,18 @@ functions =
         ]
      `since` makeVersion [3,0]
 
+  , defun "default_extensions"
+     ### liftPure getDefaultExtensions
+     <#> parameter peekText "string" "format" "format name"
+     =#> functionResult pushExtensions "FormatExtensions"
+           "default extensions enabled for `format`"
+     #? T.unlines
+        [ "Returns the list of default extensions of the given format; this"
+        , "function does not check if the format is supported, it will return"
+        , "a fallback list of extensions even for unknown formats."
+        ]
+     `since` makeVersion [3,0]
+
   , defun "extensions"
      ### liftPure getExtensionsConfig
      <#> textParam "format" "format identifier"
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/JSON.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/JSON.hs
index 6b309fbd8..586867672 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/JSON.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/JSON.hs
@@ -38,7 +38,8 @@ import qualified Data.Text as T
 documentedModule :: Module PandocError
 documentedModule = Module
   { moduleName = "pandoc.json"
-  , moduleDescription = "JSON module based on the Aeson Haskell package."
+  , moduleDescription = "JSON module to work with JSON; " <>
+                        "based on the Aeson Haskell package."
   , moduleFields = fields
   , moduleFunctions = functions
   , moduleOperations = []
@@ -59,7 +60,7 @@ fields =
 null :: LuaError e => Field e
 null = Field
   { fieldName = "null"
-  , fieldType = "userdata"
+  , fieldType = "light userdata"
   , fieldDescription = "Value used to represent the `null` JSON value."
   , fieldPushValue = pushValue Aeson.Null
   }
@@ -94,10 +95,10 @@ decode = defun "decode"
   =#> functionResult pure "any" "decoded object"
   #? T.unlines
      [ "Creates a Lua object from a JSON string. The function returns an"
-     , "[Inline], [Block], [Pandoc], [Inlines], or [Blocks] element if the"
-     , "input can be decoded into represent any of those types. Otherwise"
-     , "the default decoding is applied, using tables, booleans, numbers,"
-     , "and [null](#pandoc.json.null) to represent the JSON value."
+     , "[[Inline]], [[Block]], [[Pandoc]], [[Inlines]], or [[Blocks]] element"
+     , "if the input can be decoded into represent any of those types."
+     , "Otherwise the default decoding is applied, using tables, booleans,"
+     , "numbers, and [null](#pandoc.json.null) to represent the JSON value."
      , ""
      , "The special handling of AST elements can be disabled by setting"
      , "`pandoc_types` to `false`."
@@ -123,7 +124,7 @@ encode = defun "encode"
                 _ -> failLua
                      "Call to __tojson metamethod did not yield a string")
   <#> parameter pure "any" "object" "object to convert"
-  =#> functionResult pure "string" "JSON encoding of `object`"
+  =#> functionResult pure "string" "JSON encoding of the given `object`"
   #? T.unlines
      ["Encodes a Lua object as JSON string."
      , ""
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs
index 8336b6917..6c5d26ead 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/MediaBag.hs
@@ -39,7 +39,17 @@ import qualified Text.Pandoc.MediaBag as MB
 documentedModule :: Module PandocError
 documentedModule = Module
   { moduleName = "pandoc.mediabag"
-  , moduleDescription = "mediabag access"
+  , moduleDescription = T.unlines
+    [ "The `pandoc.mediabag` module allows accessing pandoc's media"
+    , "storage. The \"media bag\" is used when pandoc is called with the"
+    , "`--extract-media` or (for HTML only) `--embed-resources` option."
+    , ""
+    , "The module is loaded as part of module `pandoc` and can either"
+    , "be accessed via the `pandoc.mediabag` field, or explicitly"
+    , "required, e.g.:"
+    , ""
+    , "    local mb = require 'pandoc.mediabag'"
+    ]
   , moduleFields = []
   , moduleFunctions =
       [ delete  `since` makeVersion [2,7,3]
@@ -61,15 +71,18 @@ delete :: DocumentedFunction PandocError
 delete = defun "delete"
   ### (\fp -> unPandocLua $ modifyCommonState
               (\st -> st { stMediaBag = MB.deleteMedia fp (stMediaBag st) }))
-  <#> stringParam "filepath" "filename of item to delete"
+  <#> stringParam "filepath"
+      ("Filename of the item to deleted. The media bag will be " <>
+       "left unchanged if no entry with the given filename exists.")
   =#> []
-
+  #? "Removes a single entry from the media bag."
 
 -- | Delete all items from the media bag.
 empty :: DocumentedFunction PandocError
 empty = defun "empty"
   ### unPandocLua (modifyCommonState (\st -> st { stMediaBag = mempty }))
   =#> []
+  #? "Clear-out the media bag, deleting all items."
 
 -- | Fill the mediabag with all images in the document that aren't
 -- present yet.
@@ -82,7 +95,7 @@ fill = defun "fill"
   #? ("Fills the mediabag with the images in the given document.\n" <>
       "An image that cannot be retrieved will be replaced with a Span\n" <>
       "of class \"image\" that contains the image description.\n" <>
-      "" <>
+      "\n" <>
       "Images for which the mediabag already contains an item will\n" <>
       "not be processed again.")
 
@@ -93,40 +106,108 @@ insert = defun "insert"
           mb <- getMediaBag
           setMediaBag $ MB.insertMedia fp mmime contents mb
           return (Lua.NumResults 0))
-  <#> stringParam "filepath" "item file path"
-  <#> opt (textParam "mimetype" "the item's MIME type")
-  <#> parameter Lua.peekLazyByteString "string" "contents" "binary contents"
+  <#> stringParam "filepath" "filename and path relative to the output folder."
+  <#> opt (textParam "mimetype"
+           "the item's MIME type; omit if unknown or unavailable.")
+  <#> parameter Lua.peekLazyByteString "string" "contents"
+        "the binary contents of the file."
   =#> []
+  #? T.unlines
+  [ "Adds a new entry to pandoc's media bag. Replaces any existing"
+  , "media bag entry the same `filepath`."
+  , ""
+  , "Usage:"
+  , ""
+  , "    local fp = 'media/hello.txt'"
+  , "    local mt = 'text/plain'"
+  , "    local contents = 'Hello, World!'"
+  , "    pandoc.mediabag.insert(fp, mt, contents)"
+  ]
 
 -- | Returns iterator values to be used with a Lua @for@ loop.
 items :: DocumentedFunction PandocError
 items = defun "items"
   ### (do
-          mb <-unPandocLua getMediaBag
+          mb <- unPandocLua getMediaBag
           let pushItem (fp, mimetype, contents) = do
                 Lua.pushString fp
                 Lua.pushText mimetype
                 Lua.pushByteString $ BL.toStrict contents
                 return (Lua.NumResults 3)
           Lua.pushIterator pushItem (MB.mediaItems mb))
-  =?> "Iterator triple"
+  =?> T.unlines
+  [ "Iterator triple:"
+  , ""
+  , "-   The iterator function; must be called with the iterator"
+  , "    state and the current iterator value."
+  , "-   Iterator state -- an opaque value to be passed to the"
+  , "    iterator function."
+  , "-   Initial iterator value."
+  ]
+  #? T.unlines
+  [ "Returns an iterator triple to be used with Lua's generic `for`"
+  , "statement. The iterator returns the filepath, MIME type, and"
+  , "content of a media bag item on each invocation. Items are"
+  , "processed one-by-one to avoid excessive memory use."
+  , ""
+  , "This function should be used only when full access to all items,"
+  , "including their contents, is required. For all other cases,"
+  , "[`list`](#pandoc.mediabag.list) should be preferred."
+  , ""
+  , "Usage:"
+  , ""
+  , "    for fp, mt, contents in pandoc.mediabag.items() do"
+  , "      -- print(fp, mt, contents)"
+  , "    end"
+  ]
 
 -- | Function to lookup a value in the mediabag.
 lookup :: DocumentedFunction PandocError
 lookup = defun "lookup"
-  ### (\fp -> unPandocLua (MB.lookupMedia fp <$> getMediaBag) >>= \case
-          Nothing   -> 1 <$ Lua.pushnil
-          Just item -> 2 <$ do
-            Lua.pushText $ MB.mediaMimeType item
-            Lua.pushLazyByteString $ MB.mediaContents item)
-  <#> stringParam "filepath" "path of item to lookup"
-  =?> "MIME type and contents"
+  ### (\fp -> unPandocLua (MB.lookupMedia fp <$> getMediaBag))
+  <#> stringParam "filepath" "name of the file to look up."
+  =#> mconcat
+      [ functionResult
+          (maybe Lua.pushnil (Lua.pushText . MB.mediaMimeType))
+          "string"
+          "The entry's MIME type, or nil if the file was not found."
+      , functionResult
+          (maybe Lua.pushnil (Lua.pushLazyByteString . MB.mediaContents))
+          "string"
+          "Contents of the file, or nil if the file was not found."
+      ]
+  #? T.unlines
+  [ "Lookup a media item in the media bag, and return its MIME type"
+  , "and contents."
+  , ""
+  , "Usage:"
+  , ""
+  , "    local filename = 'media/diagram.png'"
+  , "    local mt, contents = pandoc.mediabag.lookup(filename)"
+  ]
 
 -- | Function listing all mediabag items.
 list :: DocumentedFunction PandocError
 list = defun "list"
   ### (unPandocLua (MB.mediaDirectory <$> getMediaBag))
-  =#> functionResult (pushPandocList pushEntry) "table" "list of entry triples"
+  =#> functionResult (pushPandocList pushEntry) "table"
+        ("A list of elements summarizing each entry in the media\n" <>
+         "bag. The summary item contains the keys `path`, `type`, and\n" <>
+         "`length`, giving the filepath, MIME type, and length of\n" <>
+         "contents in bytes, respectively.")
+  #? T.unlines
+  [ "Get a summary of the current media bag contents."
+  , ""
+  , "Usage:"
+  , ""
+  , "    -- calculate the size of the media bag."
+  , "    local mb_items = pandoc.mediabag.list()"
+  , "    local sum = 0"
+  , "    for i = 1, #mb_items do"
+  , "        sum = sum + mb_items[i].length"
+  , "    end"
+  , "    print(sum)"
+  ]
  where
   pushEntry :: (FilePath, MimeType, Int) -> LuaE PandocError ()
   pushEntry (fp, mimeType, contentLength) = do
@@ -138,13 +219,29 @@ list = defun "list"
 -- | Lua function to retrieve a new item.
 fetch :: DocumentedFunction PandocError
 fetch = defun "fetch"
-  ### (\src -> do
-          (bs, mimeType) <- unPandocLua $ fetchItem src
-          Lua.pushText $ fromMaybe "" mimeType
-          Lua.pushByteString bs
-          return 2)
-  <#> textParam "src" "URI to fetch"
-  =?> "Returns two string values: the fetched contents and the mimetype."
+  ### (unPandocLua . fetchItem)
+  <#> textParam "source" "path to a resource; either a local file path or URI"
+  =#> ( functionResult (Lua.pushText . fromMaybe "" . snd) "string"
+        "The entry's MIME type, or `nil` if the file was not found."
+        <>
+        functionResult (Lua.pushByteString . fst) "string"
+        "Contents of the file, or `nil` if the file was not found."
+      )
+  #? T.unlines
+  [ "Fetches the given source from a URL or local file. Returns two"
+  , "values: the contents of the file and the MIME type (or an empty"
+  , "string)."
+  , ""
+  , "The function will first try to retrieve `source` from the"
+  , "mediabag; if that fails, it will try to download it or read it"
+  , "from the local file system while respecting pandoc's \"resource"
+  , "path\" setting."
+  , ""
+  , "Usage:"
+  , ""
+  , "    local diagram_url = 'https://pandoc.org/diagram.jpg'"
+  , "    local mt, contents = pandoc.mediabag.fetch(diagram_url)"
+  ]
 
 -- | Extract the mediabag or just a single entry.
 write :: DocumentedFunction PandocError
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs
index 266e502c6..763c2781e 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs
@@ -42,7 +42,7 @@ documentedModule :: Module PandocError
 documentedModule = Module
   { moduleName = "pandoc.structure"
   , moduleDescription =
-    "Access to the higher-level document structure, including" <>
+    "Access to the higher-level document structure, including " <>
     "hierarchical sections and the table of contents."
   , moduleFields = []
   , moduleFunctions =