docs(lua): move function docs to lua files

1 files changed, 46 insertions, 19 deletions

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`:
+---<pre>vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank()
+---</pre>
+---
+---You can customize the highlight group and the duration of
+---the highlight via:
+---<pre>vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
+---</pre>
+---
+---If you want to exclude visual selections from highlighting on yank, use:
+---<pre>vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
+---</pre>
+---
+--- <pre>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
+---</pre>
+
 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 = {