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/_editor.lua | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

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

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index c5a6e65e86..4e39abb2be 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -127,10 +127,10 @@ vim.log = {
 ---     timeout the process is sent the KILL signal (9) and the exit code is set to 124. Cannot
 ---     be called in |api-fast|.
 ---     - SystemCompleted is an object with the fields:
----      - code: (integer)
----      - signal: (integer)
----      - stdout: (string), nil if stdout argument is passed
----      - stderr: (string), nil if stderr argument is passed
+---       - code: (integer)
+---       - signal: (integer)
+---       - stdout: (string), nil if stdout argument is passed
+---       - stderr: (string), nil if stderr argument is passed
 ---   - kill (fun(signal: integer|string))
 ---   - write (fun(data: string|nil)) Requires `stdin=true`. Pass `nil` to close the stream.
 ---   - is_closing (fun(): boolean)
@@ -706,8 +706,8 @@ end
 --- Generates a list of possible completions for the string.
 --- String has the pattern.
 ---
----     1. Can we get it to just return things in the global namespace with that name prefix
----     2. Can we get it to return things from global namespace even with `print(` in front.
+--- 1. Can we get it to just return things in the global namespace with that name prefix
+--- 2. Can we get it to return things from global namespace even with `print(` in front.
 ---
 --- @param pat string
 function vim._expand_pat(pat, env)
@@ -885,6 +885,7 @@ do
   --- similar to the builtin completion for the `:lua` command.
   ---
   --- Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer.
+  --- @param find_start 1|0
   function vim.lua_omnifunc(find_start, _)
     if find_start == 1 then
       local line = vim.api.nvim_get_current_line()
@@ -914,6 +915,7 @@ end
 ---
 --- @see |vim.inspect()|
 --- @see |:=|
+--- @param ... any
 --- @return any # given arguments.
 function vim.print(...)
   if vim.in_fast_event() then
-- 
cgit