docs: handle whitespace in emmycomments

4 files changed, 100 insertions, 90 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 450690fe3b..5de3e98b5a 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1189,8 +1189,8 @@ format({options})                                       *vim.lsp.buf.format()*
     server clients.
 
     Parameters: ~
-      • {options}  table|nil Optional table which holds the following optional
-                   fields:
+      • {options}  (table|nil) Optional table which holds the following
+                   optional fields:
                    • formatting_options (table|nil): Can be used to specify
                      FormattingOptions. Some unspecified options will be
                      automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#formattingOptions
@@ -1204,10 +1204,10 @@ format({options})                                       *vim.lsp.buf.format()*
                      Receives a client as argument and must return a boolean.
                      Clients matching the predicate are included. Example:               • >lua
 
-              -- Never request typescript-language-server for formatting
-              vim.lsp.buf.format {
-                filter = function(client) return client.name ~= "tsserver" end
-              }
+               -- Never request typescript-language-server for formatting
+               vim.lsp.buf.format {
+                 filter = function(client) return client.name ~= "tsserver" end
+               }
 <
                    • async boolean|nil If true the method won't block.
                      Defaults to false. Editing the buffer while formatting
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index d7b023a4ec..81449bc454 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1423,15 +1423,16 @@ keycode({str})                                                 *vim.keycode()*
     Translate keycodes.
 
     Example: >lua
-      local k = vim.keycode
-      vim.g.mapleader = k'<bs>'
+
+       local k = vim.keycode
+       vim.g.mapleader = k'<bs>'
 <
 
     Parameters: ~
-      • {str}  string String to be converted.
+      • {str}  (string) String to be converted.
 
     Return: ~
-        string
+        (string)
 
     See also: ~
       • |nvim_replace_termcodes()|
@@ -1527,7 +1528,8 @@ print({...})                                                     *vim.print()*
     "Pretty prints" the given arguments and returns them unmodified.
 
     Example: >lua
-      local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true))
+
+       local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true))
 <
 
     Return: ~
@@ -1579,19 +1581,19 @@ system({cmd}, {opts}, {on_exit})                                *vim.system()*
 
     Examples: >lua
 
-      local on_exit = function(obj)
-        print(obj.code)
-        print(obj.signal)
-        print(obj.stdout)
-        print(obj.stderr)
-      end
+       local on_exit = function(obj)
+         print(obj.code)
+         print(obj.signal)
+         print(obj.stdout)
+         print(obj.stderr)
+       end
 
-      -- Run asynchronously
-      vim.system({'echo', 'hello'}, { text = true }, on_exit)
+       -- Run asynchronously
+       vim.system({'echo', 'hello'}, { text = true }, on_exit)
 
-      -- Run synchronously
-      local obj = vim.system({'echo', 'hello'}, { text = true }):wait()
-      -- { code = 0, signal = 0, stdout = 'hello', stderr = '' }
+       -- Run synchronously
+       local obj = vim.system({'echo', 'hello'}, { text = true }):wait()
+       -- { code = 0, signal = 0, stdout = 'hello', stderr = '' }
 <
 
     See |uv.spawn()| for more details.
@@ -1775,8 +1777,8 @@ gsplit({s}, {sep}, {opts})                                      *vim.gsplit()*
 <
 
     Parameters: ~
-      • {s}     string String to split
-      • {sep}   string Separator or pattern
+      • {s}     (string) String to split
+      • {sep}   (string) Separator or pattern
       • {opts}  (table|nil) Keyword arguments |kwargs|:
                 • plain: (boolean) Use `sep` literally (as in string.find).
                 • trimempty: (boolean) Discard empty segments at start and end
@@ -2501,7 +2503,8 @@ get_option({filetype}, {option})                   *vim.filetype.get_option()*
     files.
 
     Example: >lua
-      vim.filetype.get_option('vim', 'commentstring')
+
+       vim.filetype.get_option('vim', 'commentstring')
 <
 
     Note: this uses |nvim_get_option_value()| but caches the result. This
@@ -2509,8 +2512,8 @@ get_option({filetype}, {option})                   *vim.filetype.get_option()*
     may not reflect later changes.
 
     Parameters: ~
-      • {filetype}  string Filetype
-      • {option}    string Option name
+      • {filetype}  (string) Filetype
+      • {option}    (string) Option name
 
     Return: ~
         string|boolean|integer: Option value
@@ -2649,7 +2652,7 @@ dir({path}, {opts})                                             *vim.fs.dir()*
       • {path}  (string) An absolute or relative path to the directory to
                 iterate over. The path is first normalized
                 |vim.fs.normalize()|.
-      • {opts}  table|nil Optional keyword arguments:
+      • {opts}  (table|nil) Optional keyword arguments:
                 • depth: integer|nil How deep the traverse (default 1)
                 • skip: (fun(dir_name: string): boolean)|nil Predicate to
                   control traversal. Return false to stop searching the
@@ -2847,10 +2850,10 @@ and dependencies on the current system.
 
 Example: >lua
 
-  local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false})
-  if vim.version.gt(v, {3, 2, 0}) then
-    -- ...
-  end
+   local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false})
+   if vim.version.gt(v, {3, 2, 0}) then
+     -- ...
+   end
 
 <
 
@@ -2864,33 +2867,33 @@ tested against a version, using |vim.version.range()|.
 Supported range specs are shown in the following table. Note: suffixed
 versions (1.2.3-rc1) are not matched. >
 
-  1.2.3             is 1.2.3
-  =1.2.3            is 1.2.3
-  >1.2.3            greater than 1.2.3
-  <1.2.3            before 1.2.3
-  >=1.2.3           at least 1.2.3
-  ~1.2.3            is >=1.2.3 <1.3.0       "reasonably close to 1.2.3"
-  ^1.2.3            is >=1.2.3 <2.0.0       "compatible with 1.2.3"
-  ^0.2.3            is >=0.2.3 <0.3.0       (0.x.x is special)
-  ^0.0.1            is =0.0.1               (0.0.x is special)
-  ^1.2              is >=1.2.0 <2.0.0       (like ^1.2.0)
-  ~1.2              is >=1.2.0 <1.3.0       (like ~1.2.0)
-  ^1                is >=1.0.0 <2.0.0       "compatible with 1"
-  ~1                same                    "reasonably close to 1"
-  1.x               same
-  1.*               same
-  1                 same
-  *                 any version
-  x                 same
+   1.2.3             is 1.2.3
+   =1.2.3            is 1.2.3
+   >1.2.3            greater than 1.2.3
+   <1.2.3            before 1.2.3
+   >=1.2.3           at least 1.2.3
+   ~1.2.3            is >=1.2.3 <1.3.0       "reasonably close to 1.2.3"
+   ^1.2.3            is >=1.2.3 <2.0.0       "compatible with 1.2.3"
+   ^0.2.3            is >=0.2.3 <0.3.0       (0.x.x is special)
+   ^0.0.1            is =0.0.1               (0.0.x is special)
+   ^1.2              is >=1.2.0 <2.0.0       (like ^1.2.0)
+   ~1.2              is >=1.2.0 <1.3.0       (like ~1.2.0)
+   ^1                is >=1.0.0 <2.0.0       "compatible with 1"
+   ~1                same                    "reasonably close to 1"
+   1.x               same
+   1.*               same
+   1                 same
+   *                 any version
+   x                 same
 
-  1.2.3 - 2.3.4     is >=1.2.3 <=2.3.4
+   1.2.3 - 2.3.4     is >=1.2.3 <=2.3.4
 
-  Partial right: missing pieces treated as x (2.3 => 2.3.x).
-  1.2.3 - 2.3       is >=1.2.3 <2.4.0
-  1.2.3 - 2         is >=1.2.3 <3.0.0
+   Partial right: missing pieces treated as x (2.3 => 2.3.x).
+   1.2.3 - 2.3       is >=1.2.3 <2.4.0
+   1.2.3 - 2         is >=1.2.3 <3.0.0
 
-  Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
-  1.2 - 2.3.0       is 1.2.0 - 2.3.0
+   Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
+   1.2 - 2.3.0       is 1.2.0 - 2.3.0
 
 <
 
@@ -2985,11 +2988,11 @@ parse({version}, {opts})                                 *vim.version.parse()*
 range({spec})                                            *vim.version.range()*
     Parses a semver |version-range| "spec" and returns a range object: >
 
-      {
-        from: Version
-        to: Version
-        has(v: string|Version)
-      }
+       {
+         from: Version
+         to: Version
+         has(v: string|Version)
+       }
 <
 
     `:has()` checks if a version is in the range (inclusive `from`, exclusive
@@ -2997,20 +3000,20 @@ range({spec})                                            *vim.version.range()*
 
     Example: >lua
 
-      local r = vim.version.range('1.0.0 - 2.0.0')
-      print(r:has('1.9.9'))       -- true
-      print(r:has('2.0.0'))       -- false
-      print(r:has(vim.version())) -- check against current Nvim version
+       local r = vim.version.range('1.0.0 - 2.0.0')
+       print(r:has('1.9.9'))       -- true
+       print(r:has('2.0.0'))       -- false
+       print(r:has(vim.version())) -- check against current Nvim version
 <
 
     Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: >lua
 
-      local r = vim.version.range('1.0.0 - 2.0.0')
-      print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
+       local r = vim.version.range('1.0.0 - 2.0.0')
+       print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
 <
 
     Parameters: ~
-      • {spec}  string Version range "spec"
+      • {spec}  (string) Version range "spec"
 
     See also: ~
       • # https://github.com/npm/node-semver#ranges
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 9f17b9fb54..bb0d435f4a 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -793,17 +793,17 @@ get_filetypes({lang})                *vim.treesitter.language.get_filetypes()*
     Get the filetypes associated with the parser named {lang}.
 
     Parameters: ~
-      • {lang}  string Name of parser
+      • {lang}  (string) Name of parser
 
     Return: ~
         string[] filetypes
 
 get_lang({filetype})                      *vim.treesitter.language.get_lang()*
     Parameters: ~
-      • {filetype}  string
+      • {filetype}  (string)
 
     Return: ~
-        string|nil
+        (string|nil)
 
 inspect({lang})                            *vim.treesitter.language.inspect()*
     Inspects the provided language.
@@ -821,7 +821,7 @@ register({lang}, {filetype})              *vim.treesitter.language.register()*
     Register a parser named {lang} to be used for {filetype}(s).
 
     Parameters: ~
-      • {lang}      string Name of parser
+      • {lang}      (string) Name of parser
       • {filetype}  string|string[] Filetype(s) to associate with lang
 
 
@@ -1051,7 +1051,9 @@ contents.
 To create a LanguageTree (parser object) for a given buffer and language, use:
 
 >lua
-    local parser = vim.treesitter.get_parser(bufnr, lang)
+
+     local parser = vim.treesitter.get_parser(bufnr, lang)
+
 <
 
 (where `bufnr=0` means current buffer). `lang` defaults to 'filetype'.
@@ -1062,7 +1064,9 @@ it wants incremental updates.
 Whenever you need to access the current syntax tree, parse the buffer:
 
 >lua
-    local tree = parser:parse()
+
+     local tree = parser:parse()
+
 <
 
 This returns a table of immutable |treesitter-tree| objects representing
@@ -1175,22 +1179,23 @@ LanguageTree:register_cbs({cbs}, {recursive})
     Registers callbacks for the |LanguageTree|.
 
     Parameters: ~
-      • {cbs}         (table) An |nvim_buf_attach()|-like table argument with
-                      the following handlers:
-                      • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback.
-                      • `on_changedtree` : a callback that will be called
-                        every time the tree has syntactical changes. It will
-                        be passed two arguments: a table of the ranges (as
-                        node ranges) that changed and the changed tree.
-                      • `on_child_added` : emitted when a child is added to
-                        the tree.
-                      • `on_child_removed` : emitted when a child is removed
-                        from the tree.
-                      • `on_detach` : emitted when the buffer is detached, see
-                        |nvim_buf_detach_event|. Takes one argument, the
-                        number of the buffer.
-      • {recursive?}  boolean Apply callbacks recursively for all children.
-                      Any new children will also inherit the callbacks.
+      • {cbs}        (table) An |nvim_buf_attach()|-like table argument with
+                     the following handlers:
+                     • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback.
+                     • `on_changedtree` : a callback that will be called every
+                       time the tree has syntactical changes. It will be
+                       passed two arguments: a table of the ranges (as node
+                       ranges) that changed and the changed tree.
+                     • `on_child_added` : emitted when a child is added to the
+                       tree.
+                     • `on_child_removed` : emitted when a child is removed
+                       from the tree.
+                     • `on_detach` : emitted when the buffer is detached, see
+                       |nvim_buf_detach_event|. Takes one argument, the number
+                       of the buffer.
+      • {recursive}  (boolean|nil) Apply callbacks recursively for all
+                     children. Any new children will also inherit the
+                     callbacks.
 
 LanguageTree:source()                                  *LanguageTree:source()*
     Returns the source content of the language tree (bufnr or string).
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index bb5214f091..b0eb4c086c 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -328,6 +328,7 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename)
       line = string_trim(inStream:getLine())
       l = l + 1
       if string.sub(line, 1, 2) == '--' then -- it's a comment
+        line = line:gsub('^---%s+@', '---@')
         -- Allow people to write style similar to EmmyLua (since they are basically the same)
         -- instead of silently skipping things that start with ---
         if string.sub(line, 3, 3) == '@' then -- it's a magic comment
@@ -341,6 +342,7 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename)
         if vim.startswith(line, '---@cast')
           or vim.startswith(line, '---@diagnostic')
           or vim.startswith(line, '---@overload')
+          or vim.startswith(line, '---@meta')
           or vim.startswith(line, '---@type') then
           -- Ignore LSP directives
           outStream:writeln('// gg:"' .. line .. '"')