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

6 files changed, 291 insertions, 137 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index fda74c06f..a78455577 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -4099,18 +4099,22 @@ Usage:
       print('type of metavalue `author`:', pandoc.utils.type(meta.author))
     end
 
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.mediabag -->
+
 # Module pandoc.mediabag
 
 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.:
+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'
 
+## Functions {#pandoc.mediabag-functions}
+
 ### delete {#pandoc.mediabag.delete}
 
 `delete (filepath)`
@@ -4120,8 +4124,10 @@ Removes a single entry from the media bag.
 Parameters:
 
 `filepath`
-:   filename of the item to be deleted. The media bag will be
-    left unchanged if no entry with the given filename exists.
+:   Filename of the item to deleted. The media bag will be left
+    unchanged if no entry with the given filename exists. (string)
+
+*Since: 2.7.3*
 
 ### empty {#pandoc.mediabag.empty}
 
@@ -4129,50 +4135,88 @@ Parameters:
 
 Clear-out the media bag, deleting all items.
 
+*Since: 2.7.3*
+
+### fetch {#pandoc.mediabag.fetch}
+
+`fetch (source)`
+
+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)
+
+Parameters:
+
+`source`
+:   path to a resource; either a local file path or URI (string)
+
+Returns:
+
+-   The entry's MIME type, or `nil` if the file was not found.
+    (string)
+-   Contents of the file, or `nil` if the file was not found.
+    (string)
+
+*Since: 2.0*
+
 ### fill {#pandoc.mediabag.fill}
 
 `fill (doc)`
 
-Fills the mediabag with the images in the given document. An
-image that cannot be retrieved will be replaced with a Span of
-class "image" that contains the image description.
+Fills the mediabag with the images in the given document. An image
+that cannot be retrieved will be replaced with a Span of class
+"image" that contains the image description.
 
-Images for which the mediabag already contains an item will
-not be processed again.
+Images for which the mediabag already contains an item will not be
+processed again.
 
 Parameters:
 
 `doc`
-:   document from which to fill the mediabag ([Pandoc](#type-pandoc))
+:   document from which to fill the mediabag ([Pandoc])
 
 Returns:
 
--   modified document ([Pandoc](#type-pandoc))
+-   modified document ([Pandoc])
+
+*Since: 2.19*
 
 ### insert {#pandoc.mediabag.insert}
 
-`insert (filepath, mime_type, contents)`
+`insert (filepath, mimetype, contents)`
 
 Adds a new entry to pandoc's media bag. Replaces any existing
-mediabag entry with the same `filepath`.
+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)
 
 Parameters:
 
 `filepath`
-:   filename and path relative to the output folder.
+:   filename and path relative to the output folder. (string)
 
-`mime_type`
-:   the file's MIME type; use `nil` if unknown or unavailable.
+`mimetype`
+:   the item's MIME type; omit if unknown or unavailable. (string)
 
 `contents`
-:   the binary contents of the file.
+:   the binary contents of the file. (string)
 
-Usage:
-
-    local fp = "media/hello.txt"
-    local mt = "text/plain"
-    local contents = "Hello, World!"
-    pandoc.mediabag.insert(fp, mt, contents)
+*Since: 2.0*
 
 ### items {#pandoc.mediabag.items}
 
@@ -4185,15 +4229,7 @@ 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.
-
-Returns:
-
--   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.
+[`list`] should be preferred.
 
 Usage:
 
@@ -4201,17 +4237,24 @@ Usage:
       -- print(fp, mt, contents)
     end
 
+Returns:
+
+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.
+
+*Since: 2.7.3*
+
 ### list {#pandoc.mediabag.list}
 
 `list ()`
 
 Get a summary of the current media bag contents.
 
-Returns: A list of elements summarizing each entry in the media
-bag. The summary item contains the keys `path`, `type`, and
-`length`, giving the filepath, MIME type, and length of contents
-in bytes, respectively.
-
 Usage:
 
     -- calculate the size of the media bag.
@@ -4222,55 +4265,40 @@ Usage:
     end
     print(sum)
 
-### lookup {#pandoc.mediabag.lookup}
-
-`lookup (filepath)`
+Returns:
 
-Lookup a media item in the media bag, and return its MIME type
-and contents.
+-   A list of elements summarizing each entry in the media bag.
+    The summary item contains the keys `path`, `type`, and
+    `length`, giving the filepath, MIME type, and length of
+    contents in bytes, respectively. (table)
 
-Parameters:
+*Since: 2.0*
 
-`filepath`
-:   name of the file to look up.
+### lookup {#pandoc.mediabag.lookup}
 
-Returns:
+`lookup (filepath)`
 
--   the entry's MIME type, or nil if the file was not found.
--   contents of the file, or nil if the file was not found.
+Lookup a media item in the media bag, and return its MIME type and
+contents.
 
 Usage:
 
-    local filename = "media/diagram.png"
+    local filename = 'media/diagram.png'
     local mt, contents = pandoc.mediabag.lookup(filename)
 
-### fetch {#pandoc.mediabag.fetch}
-
-`fetch (source)`
-
-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.
-
 Parameters:
 
-`source`
-:   path to a resource; either a local file path or URI
+`filepath`
+:   name of the file to look up. (string)
 
 Returns:
 
--   the entries MIME type, or nil if the file was not found.
--   contents of the file, or nil if the file was not found.
+-   The entry's MIME type, or nil if the file was not found.
+    (string)
+-   Contents of the file, or nil if the file was not found.
+    (string)
 
-Usage:
-
-    local diagram_url = "https://pandoc.org/diagram.jpg"
-    local mt, contents = pandoc.mediabag.fetch(diagram_url)
+*Since: 2.0*
 
 ### write {#pandoc.mediabag.write}
 
@@ -4290,7 +4318,9 @@ Parameters:
 `fp`
 :   canonical name (relative path) of resource (string)
 
-Since: *3.0*
+*Since: 3.0*
+
+<!-- END: AUTOGENERATED CONTENT -->
 
 # Module pandoc.List
 
@@ -4493,13 +4523,15 @@ Parameters:
 `comp`
 :   Comparison function as described above.
 
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.format -->
+
 # Module pandoc.format
 
 Information about the formats supported by pandoc.
 
 ## Functions {#pandoc.format-functions}
 
-### all_extensions {#pandoc.format.default_extensions}
+### all_extensions {#pandoc.format.all_extensions}
 
 `all_extensions (format)`
 
@@ -4515,7 +4547,10 @@ Parameters:
 
 Returns:
 
--   all extensions supported for `format` (FormatExtensions)
+-   all extensions supported for `format`
+    ([FormatExtensions]{unknown-type="FormatExtensions"})
+
+*Since: 3.0*
 
 ### default_extensions {#pandoc.format.default_extensions}
 
@@ -4532,15 +4567,20 @@ Parameters:
 
 Returns:
 
--   default extensions enabled for `format` (FormatExtensions)
+-   default extensions enabled for `format`
+    ([FormatExtensions]{unknown-type="FormatExtensions"})
+
+*Since: 3.0*
 
 ### extensions {#pandoc.format.extensions}
 
-Returns the extension configuration for the given format.
-The configuration is represented as a table with all supported
-extensions as keys and their default status as value, with
-`true` indicating that the extension is enabled by default,
-while `false` marks a supported extension that's disabled.
+`extensions (format)`
+
+Returns the extension configuration for the given format. The
+configuration is represented as a table with all supported
+extensions as keys and their default status as value, with `true`
+indicating that the extension is enabled by default, while `false`
+marks a supported extension that's disabled.
 
 This function can be used to assign a value to the `Extensions`
 global in custom readers and writers.
@@ -4552,7 +4592,13 @@ Parameters:
 
 Returns:
 
--  extensions config
+-   extensions config (table)
+
+*Since: 3.0*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.json -->
 
 # Module pandoc.json
 
@@ -4562,7 +4608,7 @@ JSON module to work with JSON; based on the Aeson Haskell package.
 
 ### null {#pandoc.json.null}
 
-Value used to represent the `null` JSON value. (userdata)
+Value used to represent the `null` JSON value. (light userdata)
 
 ## Functions {#pandoc.json-functions}
 
@@ -4574,7 +4620,7 @@ 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.
+and [null] to represent the JSON value.
 
 The special handling of AST elements can be disabled by setting
 `pandoc_types` to `false`.
@@ -4591,6 +4637,8 @@ Returns:
 
 -   decoded object (any)
 
+*Since: 3.1.1*
+
 ### encode {#pandoc.json.encode}
 
 `encode (object)`
@@ -4609,7 +4657,11 @@ Parameters:
 
 Returns:
 
--   JSON encoding of the given object (string)
+-   JSON encoding of the given `object` (string)
+
+*Since: 3.1.1*
+
+<!-- END: AUTOGENERATED CONTENT -->
 
 <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.path -->
 
@@ -4840,8 +4892,8 @@ objects.
 
 # Module pandoc.structure
 
-Access to the higher-level document structure,
-includinghierarchical sections and the table of contents.
+Access to the higher-level document structure, including
+hierarchical sections and the table of contents.
 
 ## Functions {#pandoc.structure-functions}
 
@@ -6032,11 +6084,15 @@ Returns:
 
 <!-- BEGIN: GENERATED REFERENCE LINKS -->
 
-  [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html
+  [Pandoc]: #type-pandoc
+  [`list`]: #pandoc.mediabag.list
+  [Inline]: Inline
+  [Block]: #type-block
+  [Inlines]: Inlines
   [Blocks]: #type-blocks
+  [null]: #pandoc.json.null
+  [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html
   [WriterOptions]: #type-writeroptions
-  [Pandoc]: #type-pandoc
   [ChunkedDoc]: #type-chunkeddoc
-  [Block]: #type-block
   [zip.Entry]: #type-pandoc.zip.Entry
   [zip.Archive]: #type-pandoc.zip.Archive
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 =
diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua
index 91bb62aa6..61842605e 100644
--- a/tools/update-lua-module-docs.lua
+++ b/tools/update-lua-module-docs.lua
@@ -1,5 +1,5 @@
-local ipairs, load, next, pairs, print, tostring, type =
-  ipairs, load, next, pairs, print, tostring, type
+local ipairs, load, next, pairs, print, tostring, type, warn =
+  ipairs, load, next, pairs, print, tostring, type, warn
 local string, table = string, table
 local _G, arg = _G, arg