From 67f53323446d45bad7a22e92493f6402316a8ba1 Mon Sep 17 00:00:00 2001
From: Jongwook Choi <wookayin@gmail.com>
Date: Thu, 28 Dec 2023 18:00:30 -0500
Subject: fix(docs): clean up non-docstring comments for vimdoc gen

These non-docstring comments can be included into doxygen's brief
description and then appear in the succeeding function documentation.
---
 runtime/lua/vim/lsp/util.lua | 2 +-
 runtime/lua/vim/shared.lua   | 2 +-
 runtime/lua/vim/text.lua     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

(limited to 'runtime/lua')

diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index ba7ce3c2b6..44465f6cff 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -1069,7 +1069,7 @@ function M.show_document(location, offset_encoding, opts)
   -- location may be Location or LocationLink
   local range = location.range or location.targetSelectionRange
   if range then
-    --- Jump to new location (adjusting for encoding of characters)
+    -- Jump to new location (adjusting for encoding of characters)
     local row = range.start.line
     local col = get_line_byte_from_position(bufnr, range.start, offset_encoding)
     api.nvim_win_set_cursor(win, { row + 1, col })
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index bbbc888727..fd795aae49 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -579,7 +579,7 @@ function vim.tbl_isarray(t)
   local count = 0
 
   for k, _ in pairs(t) do
-    --- Check if the number k is an integer
+    -- Check if the number k is an integer
     if type(k) == 'number' and k == math.floor(k) then
       count = count + 1
     else
diff --git a/runtime/lua/vim/text.lua b/runtime/lua/vim/text.lua
index cfb0f9b821..576b962838 100644
--- a/runtime/lua/vim/text.lua
+++ b/runtime/lua/vim/text.lua
@@ -1,4 +1,4 @@
---- Text processing functions.
+-- Text processing functions.
 
 local M = {}
 
-- 
cgit 


From 4e9298ecdf945b4d16c2c6e6e4ed82b97880917c Mon Sep 17 00:00:00 2001
From: Jongwook Choi <wookayin@gmail.com>
Date: Thu, 28 Dec 2023 17:50:05 -0500
Subject: refactor(gen_vimdoc): generate function doc from metadata, not from
 xml

Problem:

For function definitions to be included in the vimdoc (formatted) and
to be exported as mpack data (unformatted), we had two internal
representations of the same function/API metadata in duplicate;
one is FunctionDoc (which was previously a dict), and the other is
doxygen XML DOM from which vimdoc (functions sections) was generated.

Solution:

We should have a single path and unified data representation
(i.e. FunctionDoc) that contains all the metadata and information about
function APIs, from which both of mpack export and vimdoc are generated.
I.e., vimdocs are no longer generated directly from doxygen XML nodes,
but generated via:

  (XML DOM Nodes) ------------> FunctionDoc ------> mpack (unformatted)
                   Recursive     Internal     |
                   Formatting    Metadata     +---> vimdoc (formatted)

This refactoring eliminates the hacky and ugly use of `fmt_vimhelp` in
`fmt_node_as_vimhelp()` and all other helper functions! This way,
`fmt_node_as_vimhelp()` can simplified as it no longer needs to handle
generating of function docs, which needs to be done only in the topmost
level of recursion.
---
 runtime/lua/vim/_meta/api.lua | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'runtime/lua')

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index c0dfa7635b..b6ce3fce8a 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -73,6 +73,9 @@ function vim.api.nvim__id_dictionary(dct) end
 function vim.api.nvim__id_float(flt) end
 
 --- @private
+--- NB: if your UI doesn't use hlstate, this will not return hlstate first
+--- time.
+---
 --- @param grid integer
 --- @param row integer
 --- @param col integer
-- 
cgit