From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Thu, 15 Feb 2024 17:16:04 +0000
Subject: feat(docs): replace lua2dox.lua

Problem:

The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.

Solution:

Re-implement the flow using Lua, LPEG and treesitter.

- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
  - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
  - LPEG for C parsing (see `scripts/cdoc_parser.lua`)
  - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
  - Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
   - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
---
 runtime/lua/vim/iter.lua | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index d720745110..798428014d 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,4 +1,4 @@
----@defgroup vim.iter
+--- @brief
 ---
 --- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
 --- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
@@ -66,6 +66,7 @@
 
 ---@class IterMod
 ---@operator call:Iter
+
 local M = {}
 
 ---@class Iter
@@ -599,7 +600,7 @@ end
 --- -- 12
 ---
 --- ```
----
+---@param f any
 ---@return any
 function Iter.find(self, f)
   if type(f) ~= 'function' then
@@ -645,6 +646,7 @@ end
 ---
 ---@see Iter.find
 ---
+---@param f any
 ---@return any
 ---@diagnostic disable-next-line: unused-local
 function Iter.rfind(self, f) -- luacheck: no unused args
@@ -724,6 +726,7 @@ function Iter.nextback(self) -- luacheck: no unused args
   error('nextback() requires a list-like table')
 end
 
+--- @nodoc
 function ListIter.nextback(self)
   if self._head ~= self._tail then
     local inc = self._head < self._tail and 1 or -1
@@ -754,6 +757,7 @@ function Iter.peekback(self) -- luacheck: no unused args
   error('peekback() requires a list-like table')
 end
 
+---@nodoc
 function ListIter.peekback(self)
   if self._head ~= self._tail then
     local inc = self._head < self._tail and 1 or -1
-- 
cgit