docs: auto-generate docs for `vim.lpeg` and `vim.re`

- Add section `VIM.LPEG` and `VIM.RE` to docs/lua.txt.

- Add `_meta/re.lua` which adds luadoc and type annotations, for the
  vendored `vim.re` package.

- Fix minor style issues on `_meta/lpeg.lua` luadoc for better vimdocs
  generation.

- Fix a bug on `gen_vimdoc` where non-helptags in verbatim code blocks
  were parsed as helptags, affecting code examples on `vim.lpeg.Cf`,
  etc.

- Also move the `vim.regex` section below so that it can be located
  closer to `vim.lpeg` and `vim.re`.

3 files changed, 87 insertions, 3 deletions

diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 42c9a6449e..5bd502a7c8 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -1,7 +1,24 @@
 --- @meta
+error('Cannot require a meta file')
 
--- These types were taken from https://github.com/LuaCATS/lpeg, with types being renamed to include
--- the vim namespace and with some descriptions made less verbose.
+-- These types were taken from https://github.com/LuaCATS/lpeg
+-- (based on revision 4aded588f9531d89555566bb1de27490354b91c7)
+-- with types being renamed to include the vim namespace and with some descriptions made less verbose.
+
+---@defgroup vim.lpeg
+---<pre>help
+---LPeg is a pattern-matching library for Lua, based on
+---Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+---
+---                                                                    *lua-lpeg*
+---                                                            *vim.lpeg.Pattern*
+---The LPeg library for parsing expression grammars is included as `vim.lpeg`
+---(https://www.inf.puc-rio.br/~roberto/lpeg/).
+---
+---In addition, its regex-like interface is available as |vim.re|
+---(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+---
+---</pre>
 
 --- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs).
 vim.lpeg = {}
@@ -32,6 +49,7 @@ local Pattern = {}
 --- matches anywhere.
 ---
 --- Example:
+---
 --- ```lua
 --- local pattern = lpeg.R("az") ^ 1 * -1
 --- assert(pattern:match("hello") == 6)
@@ -55,6 +73,7 @@ function vim.lpeg.match(pattern, subject, init) end
 --- we must either write a loop in Lua or write a pattern that matches anywhere.
 ---
 --- Example:
+---
 --- ```lua
 --- local pattern = lpeg.R("az") ^ 1 * -1
 --- assert(pattern:match("hello") == 6)
@@ -69,7 +88,7 @@ function Pattern:match(subject, init) end
 
 --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`.
 ---
---- @return 'pattern'|nil
+--- @return "pattern"|nil
 function vim.lpeg.type(value) end
 
 --- Returns a string with the running version of LPeg.
@@ -115,6 +134,7 @@ function vim.lpeg.B(pattern) end
 --- `lpeg.R("az", "AZ")` matches any ASCII letter.
 ---
 --- Example:
+---
 --- ```lua
 --- local pattern = lpeg.R("az") ^ 1 * -1
 --- assert(pattern:match("hello") == 6)
@@ -137,6 +157,7 @@ function vim.lpeg.S(string) end
 --- for a grammar. The created non-terminal refers to the rule indexed by `v` in the enclosing grammar.
 ---
 --- Example:
+---
 --- ```lua
 --- local b = lpeg.P({"(" * ((1 - lpeg.S "()") + lpeg.V(1)) ^ 0 * ")"})
 --- assert(b:match('((string))') == 11)
@@ -168,6 +189,7 @@ function vim.lpeg.V(v) end
 --- that table.
 ---
 --- Example:
+---
 --- ```lua
 --- lpeg.locale(lpeg)
 --- local space = lpeg.space^0
@@ -191,6 +213,7 @@ function vim.lpeg.locale(tab) end
 --- The captured value is a string. If `patt` has other captures, their values are returned after this one.
 ---
 --- Example:
+---
 --- ```lua
 --- local function split (s, sep)
 ---   sep = lpeg.P(sep)
@@ -241,6 +264,7 @@ function vim.lpeg.Cc(...) end
 --- becomes the captured value.
 ---
 --- Example:
+---
 --- ```lua
 --- local number = lpeg.R("09") ^ 1 / tonumber
 --- local list = number * ("," * number) ^ 0
@@ -267,6 +291,7 @@ function vim.lpeg.Cg(patt, name) end
 --- subject where the match occurs. The captured value is a number.
 ---
 --- Example:
+---
 --- ```lua
 --- local I = lpeg.Cp()
 --- local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end
@@ -285,6 +310,7 @@ function vim.lpeg.Cp() end
 --- value is the string resulting from all replacements.
 ---
 --- Example:
+---
 --- ```lua
 --- local function gsub (s, patt, repl)
 ---   patt = lpeg.P(patt)
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
new file mode 100644
index 0000000000..4f254b19a0
--- /dev/null
+++ b/runtime/lua/vim/_meta/re.lua
@@ -0,0 +1,57 @@
+--- @meta
+error('Cannot require a meta file')
+
+-- Documentations and Lua types for vim.re (vendored re.lua, lpeg-1.1.0)
+-- https://www.inf.puc-rio.br/~roberto/lpeg/re.html
+--
+-- Copyright © 2007-2023 Lua.org, PUC-Rio.
+-- See 'lpeg.html' for license
+
+--- @defgroup vim.re
+---<pre>help
+---The `vim.re` module provides a conventional regex-like syntax for pattern usage
+---within LPeg |vim.lpeg|.
+---
+---See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
+---documentation including regex syntax and more concrete examples.
+---
+---</pre>
+
+--- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define
+--- either an expression or a grammar. The optional {defs} table provides extra Lua values to be used
+--- by the pattern.
+--- @param string string
+--- @param defs? table
+--- @return vim.lpeg.Pattern
+function vim.re.compile(string, defs) end
+
+--- Searches the given {pattern} in the given {subject}. If it finds a match, returns the index
+--- where this occurrence starts and the index where it ends. Otherwise, returns nil.
+---
+--- An optional numeric argument {init} makes the search starts at that position in the subject
+--- string. As usual in Lua libraries, a negative value counts from the end.
+--- @param subject string
+--- @param pattern vim.lpeg.Pattern|string
+--- @param init? integer
+--- @return integer|nil the index where the occurrence starts, nil if no match
+--- @return integer|nil the index where the occurrence ends, nil if no match
+function vim.re.find(subject, pattern, init) end
+
+--- Does a global substitution, replacing all occurrences of {pattern} in the given {subject} by
+--- {replacement}.
+--- @param subject string
+--- @param pattern vim.lpeg.Pattern|string
+--- @param replacement string
+--- @return string
+function vim.re.gsub(subject, pattern, replacement) end
+
+--- Matches the given {pattern} against the given {subject}, returning all captures.
+--- @param subject string
+--- @param pattern vim.lpeg.Pattern|string
+--- @param init? integer
+--- @return integer|vim.lpeg.Capture|nil
+--- @see vim.lpeg.match()
+function vim.re.match(subject, pattern, init) end
+
+--- Updates the pre-defined character classes to the current locale.
+function vim.re.updatelocale() end
diff --git a/runtime/lua/vim/re.lua b/runtime/lua/vim/re.lua
index 007eb27ed8..114f74eb80 100644
--- a/runtime/lua/vim/re.lua
+++ b/runtime/lua/vim/re.lua
@@ -3,6 +3,7 @@
 -- written by Roberto Ierusalimschy
 --
 --- vendored from lpeg-1.1.0
+--- documentation available at runtime/lua/vim/_meta/re.lua
 
 -- imported functions and modules
 local tonumber, type, print, error = tonumber, type, print, error