From 0ac3c4d6314df5fe40571a83e157a425ab7ce16d Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Sat, 15 Jul 2023 16:55:32 +0100 Subject: docs(lua): move function docs to lua files --- runtime/lua/vim/highlight.lua | 65 ++++++++++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 19 deletions(-) (limited to 'runtime/lua/vim/highlight.lua') diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua index 86e1adb49e..97a5a1233f 100644 --- a/runtime/lua/vim/highlight.lua +++ b/runtime/lua/vim/highlight.lua @@ -1,3 +1,36 @@ +---@defgroup lua-highlight +--- +---@brief +---Nvim includes a function for highlighting a selection on yank. +--- +---To enable it, add the following to your `init.vim`: +---
vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank()
+---
+--- +---You can customize the highlight group and the duration of +---the highlight via: +---
vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
+---
+--- +---If you want to exclude visual selections from highlighting on yank, use: +---
vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
+---
+--- +--- 
help
+---vim.highlight.priorities                            *vim.highlight.priorities*
+---
+---    Table with default priorities used for highlighting:
+---        • `syntax`: `50`, used for standard syntax highlighting
+---        • `treesitter`: `100`, used for tree-sitter-based highlighting
+---        • `semantic_tokens`: `125`, used for LSP semantic token highlighting
+---        • `diagnostics`: `150`, used for code analysis such as diagnostics
+---        • `user`: `200`, used for user-triggered highlights such as LSP document
+---          symbols or `on_yank` autocommands
+---
+ local api = vim.api local M = {} @@ -10,7 +43,7 @@ M.priorities = { user = 200, } ---- Highlight range between two positions +--- Apply highlight group to range of text. --- ---@param bufnr integer Buffer number to apply highlighting to ---@param ns integer Namespace to add highlight to @@ -18,9 +51,9 @@ M.priorities = { ---@param start integer[]|string Start of region as a (line, column) tuple or string accepted by |getpos()| ---@param finish integer[]|string End of region as a (line, column) tuple or string accepted by |getpos()| ---@param opts table|nil Optional parameters --- - regtype type of range (see |setreg()|, default charwise) --- - inclusive boolean indicating whether the range is end-inclusive (default false) --- - priority number indicating priority of highlight (default priorities.user) +--- - regtype type of range (see |setreg()|, default charwise) +--- - inclusive boolean indicating whether the range is end-inclusive (default false) +--- - priority number indicating priority of highlight (default priorities.user) function M.range(bufnr, ns, higroup, start, finish, opts) opts = opts or {} local regtype = opts.regtype or 'v' @@ -46,22 +79,16 @@ end local yank_ns = api.nvim_create_namespace('hlyank') local yank_timer ---- Highlight the yanked region ---- ---- use from init.vim via ---- au TextYankPost * lua vim.highlight.on_yank() ---- customize highlight group and timeout via ---- au TextYankPost * lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} ---- customize conditions (here: do not highlight a visual selection) via ---- au TextYankPost * lua vim.highlight.on_yank {on_visual=false} + +--- Highlight the yanked text --- --- @param opts table|nil Optional parameters --- - higroup highlight group for yanked region (default "IncSearch") --- - timeout time in ms before highlight is cleared (default 150) --- - on_macro highlight when executing macro (default false) --- - on_visual highlight when yanking visual selection (default true) --- - event event structure (default vim.v.event) --- - priority integer priority (default |vim.highlight.priorities|`.user`) +--- @param opts table|nil Optional parameters +--- - higroup highlight group for yanked region (default "IncSearch") +--- - timeout time in ms before highlight is cleared (default 150) +--- - on_macro highlight when executing macro (default false) +--- - on_visual highlight when yanking visual selection (default true) +--- - event event structure (default vim.v.event) +--- - priority integer priority (default |vim.highlight.priorities|`.user`) function M.on_yank(opts) vim.validate({ opts = { -- cgit v1.3-3-g829e From c2d7c2826ca77b0ca31bec511fdcdf1e4abaf946 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 17 Jul 2023 15:13:54 +0100 Subject: docs(lua): change *lua-foo* -> *vim.foo* --- runtime/doc/lua.txt | 51 ++++++++++++++++++--------------------- runtime/lua/vim/_meta/builtin.lua | 2 +- runtime/lua/vim/_meta/json.lua | 4 +-- runtime/lua/vim/_meta/mpack.lua | 4 +-- runtime/lua/vim/_meta/regex.lua | 2 +- runtime/lua/vim/highlight.lua | 2 +- runtime/lua/vim/iter.lua | 4 +-- runtime/lua/vim/version.lua | 2 +- scripts/gen_vimdoc.py | 6 ++++- scripts/lua2dox.lua | 5 ++++ 10 files changed, 44 insertions(+), 38 deletions(-) (limited to 'runtime/lua/vim/highlight.lua') diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index d53b66a865..3b25e2744e 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -573,7 +573,7 @@ The Lpeg library for parsing expression grammars is being included as interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). ============================================================================== -VIM.HIGHLIGHT *lua-highlight* +VIM.HIGHLIGHT *vim.highlight* Nvim includes a function for highlighting a selection on yank. @@ -637,7 +637,7 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) ============================================================================== -VIM.REGEX *lua-regex* +VIM.REGEX *vim.regex* Vim regexes can be used directly from Lua. Currently they only allow @@ -678,7 +678,7 @@ vim.regex:match_str({str}) *regex:match_str()* ============================================================================== -VIM.DIFF *lua-diff* +VIM.DIFF *vim.diff* vim.diff({a}, {b}, {opts}) *vim.diff()* Run diff on strings {a} and {b}. Any indices returned by this function, @@ -747,13 +747,11 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* ============================================================================== -VIM.MPACK *lua-mpack* +VIM.MPACK *vim.mpack* -The *vim.mpack* module provides encoding and decoding of Lua objects to -and from msgpack-encoded strings. Supports |vim.NIL| and -|vim.empty_dict()|. - +This module provides encoding and decoding of Lua objects to and from +msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. vim.mpack.decode({str}) *vim.mpack.decode()* Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. @@ -766,12 +764,11 @@ vim.mpack.encode({obj}) *vim.mpack.encode()* ============================================================================== -VIM.JSON *lua-json* - +VIM.JSON *vim.json* -The *vim.json* module provides encoding and decoding of Lua objects to and -from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. +This module provides encoding and decoding of Lua objects to and from +JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. vim.json.decode({str}, {opts}) *vim.json.decode()* Decodes (or "unpacks") the JSON-encoded {str} to a Lua object. @@ -806,7 +803,7 @@ vim.json.encode({obj}) *vim.json.encode()* ============================================================================== -VIM.SPELL *lua-spell* +VIM.SPELL *vim.spell* vim.spell.check({str}) *vim.spell.check()* Check {str} for spelling errors. Similar to the Vimscript function @@ -839,7 +836,7 @@ vim.spell.check({str}) *vim.spell.check()* ============================================================================== -VIM *lua-builtin* +VIM *vim.builtin* vim.api.{func}({...}) *vim.api* @@ -1744,7 +1741,7 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* ============================================================================== -Lua module: vim.inspector *lua-inspector* +Lua module: vim.inspector *vim.inspector* vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* Get all the items at a given buffer position. @@ -2324,7 +2321,7 @@ vim.validate({opt}) *vim.validate()* ============================================================================== -Lua module: vim.loader *lua-loader* +Lua module: vim.loader *vim.loader* vim.loader.disable() *vim.loader.disable()* Disables the experimental Lua module loader: @@ -2371,7 +2368,7 @@ vim.loader.reset({path}) *vim.loader.reset()* ============================================================================== -Lua module: vim.uri *lua-uri* +Lua module: vim.uri *vim.uri* vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* Get a URI from a bufnr @@ -2412,7 +2409,7 @@ vim.uri_to_fname({uri}) *vim.uri_to_fname()* ============================================================================== -Lua module: vim.ui *lua-ui* +Lua module: vim.ui *vim.ui* vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* Prompts the user for input, allowing arbitrary (potentially asynchronous) @@ -2502,7 +2499,7 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* ============================================================================== -Lua module: vim.filetype *lua-filetype* +Lua module: vim.filetype *vim.filetype* vim.filetype.add({filetypes}) *vim.filetype.add()* Add new filetype mappings. @@ -2670,7 +2667,7 @@ vim.filetype.match({args}) *vim.filetype.match()* ============================================================================== -Lua module: vim.keymap *lua-keymap* +Lua module: vim.keymap *vim.keymap* vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* Remove an existing mapping. Examples: >lua @@ -2730,7 +2727,7 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* ============================================================================== -Lua module: vim.fs *lua-fs* +Lua module: vim.fs *vim.fs* vim.fs.basename({file}) *vim.fs.basename()* Return the basename of the given file or directory @@ -2893,7 +2890,7 @@ vim.fs.parents({start}) *vim.fs.parents()* ============================================================================== -Lua module: vim.secure *lua-secure* +Lua module: vim.secure *vim.secure* vim.secure.read({path}) *vim.secure.read()* Attempt to read the file at {path} prompting the user if the file should @@ -2933,7 +2930,7 @@ vim.secure.trust({opts}) *vim.secure.trust()* ============================================================================== -Lua module: vim.version *lua-version* +Lua module: vim.version *vim.version* The `vim.version` module provides functions for comparing versions and @@ -3116,12 +3113,12 @@ vim.version.range({spec}) *vim.version.range()* ============================================================================== -Lua module: vim.iter *lua-iter* +Lua module: vim.iter *vim.iter* -The *vim.iter* module provides a generic interface for working with -iterables: tables, lists, iterator functions, pair()/ipair()-like -iterators, and `vim.iter()` objects. +This module provides a generic interface for working with iterables: +tables, lists, iterator functions, pair()/ipair()-like iterators, and +`vim.iter()` objects. *vim.iter()* wraps its table or function argument into an *Iter* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index 384dd4351d..a1786b2cdb 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -1,6 +1,6 @@ ---@meta ----@defgroup lua-builtin +---@defgroup vim.builtin --- ---@brief 
help
 ---vim.api.{func}({...})                                                    *vim.api*
diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua
index 15e81d5004..2580b56870 100644
--- a/runtime/lua/vim/_meta/json.lua
+++ b/runtime/lua/vim/_meta/json.lua
@@ -1,8 +1,8 @@
 --- @meta
 
---- @defgroup lua-json
+--- @defgroup vim.json
 ---
---- @brief The \*vim.json\* module provides encoding and decoding of Lua objects to and
+--- This module provides encoding and decoding of Lua objects to and
 --- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
 
 --- Decodes (or "unpacks") the JSON-encoded {str} to a Lua object.
diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua
index 2764177e5c..1bcb6845b9 100644
--- a/runtime/lua/vim/_meta/mpack.lua
+++ b/runtime/lua/vim/_meta/mpack.lua
@@ -1,8 +1,8 @@
 --- @meta
 
---- @defgroup lua-mpack
+--- @defgroup vim.mpack
 ---
---- @brief The \*vim.mpack\* module provides encoding and decoding of Lua objects to and
+--- This module provides encoding and decoding of Lua objects to and
 --- from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
 
 --- Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
index afa78772da..0af1bccea5 100644
--- a/runtime/lua/vim/_meta/regex.lua
+++ b/runtime/lua/vim/_meta/regex.lua
@@ -1,6 +1,6 @@
 --- @meta
 
---- @defgroup lua-regex
+--- @defgroup vim.regex
 ---
 --- @brief Vim regexes can be used directly from Lua. Currently they only allow
 --- matching within a single line.
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index 97a5a1233f..0eb782339c 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -1,4 +1,4 @@
----@defgroup lua-highlight
+---@defgroup vim.highlight
 ---
 ---@brief
 ---Nvim includes a function for highlighting a selection on yank.
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 245a33625e..6c1afcad91 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,6 +1,6 @@
----@defgroup lua-iter
+---@defgroup vim.iter
 ---
---- @brief The \*vim.iter\* module provides a generic interface for working with
+--- This module provides a generic interface for working with
 --- iterables: tables, lists, iterator functions, pair()/ipair()-like iterators,
 --- and \`vim.iter()\` objects.
 ---
diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index cd28a9b54b..8ff8a19cb9 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -1,4 +1,4 @@
---- @defgroup lua-version
+--- @defgroup vim.version
 ---
 --- @brief The \`vim.version\` module provides functions for comparing versions and ranges
 --- conforming to the https://semver.org spec. Plugins, and plugin managers, can use this to check
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index eacf4dc24d..984939a692 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -208,7 +208,7 @@ CONFIG = {
         'helptag_fmt': lambda name: (
             '*lua-vim*' if name.lower() == '_editor' else
             '*lua-vimscript*' if name.lower() == '_options' else
-            f'*lua-{name.lower()}*'),
+            f'*vim.{name.lower()}*'),
         'fn_helptag_fmt': lambda fstem, name: (
             f'*vim.opt:{name.split(":")[-1]}()*' if ':' in name and name.startswith('Option') else
             # Exclude fstem for methods
@@ -1160,6 +1160,10 @@ def main(doxygen_config, args):
                 if doc:
                     doc_list.append(doc)
 
+            # Can't use '.' in @defgroup, so convert to '--'
+            # "vim.json" => "vim-dot-json"
+            groupname = groupname.replace('-dot-', '.')
+
             section_docs[groupname] = "\n".join(doc_list)
 
         # Generate docs for all functions in the current module.
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index b0eb4c086c..3f0d0505dd 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -416,6 +416,11 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename)
 
             magic = table.concat(magic_split, ' ')
 
+            if magic_split[1] == 'defgroup' or magic_split[1] == 'addtogroup' then
+              -- Can't use '.' in defgroup, so convert to '--'
+              magic = magic:gsub('%.', '-dot-')
+            end
+
             outStream:writeln('/// @' .. magic)
             fn_magic = checkComment4fn(fn_magic, magic)
           end
-- 
cgit v1.3-3-g829e