From 563f1b4e7da2593b4ebbb27c58ee46b4b9255b52 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 10 Jul 2023 13:50:10 +0100 Subject: [PATCH] docs: make gen_help.lua emmy aware --- doc/gitsigns.txt | 240 +++++++++++++++++++------------------- gen_help.lua | 246 ++++++++++++++++++++++++++++++++------- lua/gitsigns.lua | 5 +- lua/gitsigns/actions.lua | 228 +++++++++++++++--------------------- lua/gitsigns/attach.lua | 39 ++++--- 5 files changed, 442 insertions(+), 316 deletions(-) diff --git a/doc/gitsigns.txt b/doc/gitsigns.txt index 24fc388e..1652376b 100644 --- a/doc/gitsigns.txt +++ b/doc/gitsigns.txt @@ -47,7 +47,6 @@ of the default settings: linehl = false, -- Toggle with `:Gitsigns toggle_linehl` word_diff = false, -- Toggle with `:Gitsigns toggle_word_diff` watch_gitdir = { - interval = 1000, follow_files = true }, attach_to_untracked = true, @@ -99,8 +98,8 @@ setup({cfg}) *gitsigns.setup()* {async} Parameters: ~ - {cfg} Table object containing configuration for - Gitsigns. See |gitsigns-usage| for more details. + {cfg} (table): Configuration for Gitsigns. + See |gitsigns-usage| for more details. attach({bufnr}, {ctx}) *gitsigns.attach()* Attach Gitsigns to the buffer. @@ -109,29 +108,29 @@ attach({bufnr}, {ctx}) *gitsigns.attach()* {async} Parameters: ~ - {bufnr} (number): Buffer number - {ctx} (table|nil): - Git context data that may optionally be used to attach to any - buffer that represents a real git object. - • {file}: (string) - Path to the file represented by the buffer, relative to the - top-level. - • {toplevel}: (string) - Path to the top-level of the parent git repository. - • {gitdir}: (string) - Path to the git directory of the parent git repository - (typically the ".git/" directory). - • {commit}: (string) - The git revision that the file belongs to. - • {base}: (string|nil) - The git revision that the file should be compared to. + {bufnr} (integer): Buffer number + {ctx} (table|nil): + Git context data that may optionally be used to attach to any + buffer that represents a real git object. + • {file}: (string) + Path to the file represented by the buffer, relative to the + top-level. + • {toplevel}: (string) + Path to the top-level of the parent git repository. + • {gitdir}: (string) + Path to the git directory of the parent git repository + (typically the ".git/" directory). + • {commit}: (string) + The git revision that the file belongs to. + • {base}: (string|nil) + The git revision that the file should be compared to. detach({bufnr}) *gitsigns.detach()* Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not provided then the current buffer is used. Parameters: ~ - {bufnr} (number): Buffer number + {bufnr} (integer): Buffer number detach_all() *gitsigns.detach_all()* Detach Gitsigns from all buffers it is attached to. @@ -146,8 +145,9 @@ get_actions() *gitsigns.get_actions()* Get all the available line specific actions for the current buffer at the cursor position. - Return: ~ - Dictionary of action name to function which when called + + Returns: ~ + (table|nil): Dictionary of action name to function which when called performs action. setloclist({nr}, {target}) *gitsigns.setloclist()* @@ -160,9 +160,9 @@ setloclist({nr}, {target}) *gitsigns.setloclist()* {async} Parameters: ~ - {nr} (integer): Window number or the |window-ID|. + {nr} (integer): Window number or the |window-ID|. `0` for the current window (default). - {target} (integer or string): See |gitsigns.setqflist()|. + {target} (integer|string): See |gitsigns.setqflist()|. setqflist({target}, {opts}) *gitsigns.setqflist()* Populate the quickfix list with hunks. Automatically opens the @@ -172,7 +172,7 @@ setqflist({target}, {opts}) *gitsigns.setqflist()* {async} Parameters: ~ - {target} (integer or string): + {target} (integer|string): Specifies which files hunks are collected from. Possible values. • [integer]: The buffer with the matching buffer @@ -181,8 +181,7 @@ setqflist({target}, {opts}) *gitsigns.setqflist()* • `"all"`: All modified files for each git directory of all attached buffers in addition to the current working directory. - {opts} (table|nil): - Additional options: + {opts} (table|nil): Additional options: • {use_location_list}: (boolean) Populate the location list instead of the quickfix list. Default to `false`. @@ -222,19 +221,6 @@ diffthis({base}, {opts}) *gitsigns.diffthis()* If {base} is the index, then the opened buffer is editable and any written changes will update the index accordingly. - Parameters: ~ - {base} (string|nil): Revision to diff against. Defaults - to index. - {opts} (table|nil): - Additional options: - • {vertical}: {boolean}. Split window vertically. Defaults to - config.diff_opts.vertical. If running via command line, then - this is taken from the command modifiers. - • {split}: {string}. One of: 'aboveleft', 'belowright', - 'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to - 'aboveleft'. If running via command line, then this is taken - from the command modifiers. - Examples: > " Diff against the index :Gitsigns diffthis @@ -249,6 +235,17 @@ diffthis({base}, {opts}) *gitsigns.diffthis()* Attributes: ~ {async} + Parameters: ~ + {base} (string|nil): Revision to diff against. Defaults to index. + {opts} (table|nil): Additional options: + • {vertical}: {boolean}. Split window vertically. Defaults to + config.diff_opts.vertical. If running via command line, then + this is taken from the command modifiers. + • {split}: {string}. One of: 'aboveleft', 'belowright', + 'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to + 'aboveleft'. If running via command line, then this is taken + from the command modifiers. + reset_base({global}) *gitsigns.reset_base()* Reset the base revision to diff against back to the index. @@ -264,10 +261,6 @@ change_base({base}, {global}) *gitsigns.change_base()* Attributes: ~ {async} - Parameters:~ - {base} string|nil The object/revision to diff against. - {global} boolean|nil Change the base of all buffers. - Examples: > " Change base to 1 commit behind head :lua require('gitsigns').change_base('HEAD~1') @@ -290,43 +283,47 @@ change_base({base}, {global}) *gitsigns.change_base()* For a more complete list of ways to specify bases, see |gitsigns-revision|. + Parameters: ~ + {base} (string|nil): The object/revision to diff against. + {global} (boolean|nil): Change the base of all buffers. + blame_line({opts}) *gitsigns.blame_line()* Run git blame on the current line and show the results in a floating window. If already open, calling this will cause the window to get focus. - Parameters: ~ - {opts} (table|nil): - Additional options: - • {full}: (boolean) - Display full commit message with hunk. - • {ignore_whitespace}: (boolean) - Ignore whitespace when running blame. - Attributes: ~ {async} + Parameters: ~ + {opts} (table|nil): Additional options: + • {full}: (boolean) + Display full commit message with hunk. + • {ignore_whitespace}: (boolean) + Ignore whitespace when running blame. + get_hunks({bufnr}) *gitsigns.get_hunks()* Get hunk array for specified buffer. Parameters: ~ - {bufnr} integer: Buffer number, if not provided (or 0) + {bufnr} (integer): Buffer number, if not provided (or 0) will use current buffer. - Return: ~ - Array of hunk objects. Each hunk object has keys: - • `"type"`: String with possible values: "add", "change", - "delete" - • `"head"`: Header that appears in the unified diff - output. - • `"lines"`: Line contents of the hunks prefixed with - either `"-"` or `"+"`. - • `"removed"`: Sub-table with fields: - • `"start"`: Line number (1-based) - • `"count"`: Line count - • `"added"`: Sub-table with fields: - • `"start"`: Line number (1-based) - • `"count"`: Line count + Returns: ~ + (table|nil): Array of hunk objects. + Each hunk object has keys: + • `"type"`: String with possible values: "add", "change", + "delete" + • `"head"`: Header that appears in the unified diff + output. + • `"lines"`: Line contents of the hunks prefixed with + either `"-"` or `"+"`. + • `"removed"`: Sub-table with fields: + • `"start"`: Line number (1-based) + • `"count"`: Line count + • `"added"`: Sub-table with fields: + • `"start"`: Line number (1-based) + • `"count"`: Line count select_hunk() *gitsigns.select_hunk()* Select the hunk under the cursor. @@ -353,23 +350,23 @@ next_hunk({opts}) *gitsigns.next_hunk()* at the next hunk. Parameters: ~ - {opts} table|nil Configuration table. Keys: - • {wrap}: (boolean) - Whether to loop around file or not. Defaults - to the value 'wrapscan' - • {navigation_message}: (boolean) - Whether to show navigation messages or not. - Looks at 'shortmess' for default behaviour. - • {foldopen}: (boolean) - Expand folds when navigating to a hunk which is - inside a fold. Defaults to `true` if 'foldopen' - contains `search`. - • {preview}: (boolean) - Automatically open preview_hunk() upon navigating - to a hunk. - • {greedy}: (boolean) - Only navigate between non-contiguous hunks. Only useful if - 'diff_opts' contains `linematch`. Defaults to `true`. + {opts} (table|nil): Configuration table. Keys: + • {wrap}: (boolean) + Whether to loop around file or not. Defaults + to the value 'wrapscan' + • {navigation_message}: (boolean) + Whether to show navigation messages or not. + Looks at 'shortmess' for default behaviour. + • {foldopen}: (boolean) + Expand folds when navigating to a hunk which is + inside a fold. Defaults to `true` if 'foldopen' + contains `search`. + • {preview}: (boolean) + Automatically open preview_hunk() upon navigating + to a hunk. + • {greedy}: (boolean) + Only navigate between non-contiguous hunks. Only useful if + 'diff_opts' contains `linematch`. Defaults to `true`. reset_buffer_index() *gitsigns.reset_buffer_index()* Unstage all hunks for current buffer in the index. Note: @@ -404,17 +401,16 @@ reset_hunk({range}, {opts}) *gitsigns.reset_hunk()* meaning if a range only includes a portion of a particular hunk, only the lines within the range will be reset. - Parameters:~ - {range} table|nil List-like table of two integers making + Parameters: ~ + {range} (table|nil): List-like table of two integers making up the line range from which you want to reset the hunks. If running via command line, then this is taken from the command modifiers. - {opts} table|nil Additional options: + {opts} (table|nil): Additional options: • {greedy}: (boolean) Stage all contiguous hunks. Only useful if 'diff_opts' contains `linematch`. Defaults to `true`. - stage_hunk({range}, {opts}) *gitsigns.stage_hunk()* Stage the hunk at the cursor position, or all lines in the given range. If {range} is provided, all lines in the given @@ -425,76 +421,76 @@ stage_hunk({range}, {opts}) *gitsigns.stage_hunk()* Attributes: ~ {async} - Parameters:~ - {range} table|nil List-like table of two integers making + Parameters: ~ + {range} (table|nil): List-like table of two integers making up the line range from which you want to stage the hunks. If running via command line, then this is taken from the command modifiers. - {opts} table|nil Additional options: + {opts} (table|nil): Additional options: • {greedy}: (boolean) Stage all contiguous hunks. Only useful if 'diff_opts' contains `linematch`. Defaults to `true`. - toggle_deleted({value}) *gitsigns.toggle_deleted()* Toggle |gitsigns-config-show_deleted| - Parameters:~ - {value} boolean|nil Value to set toggle. If `nil` - the toggle value is inverted. + Parameters: ~ + {value} (boolean|nil): Value to set toggle. If `nil` + the toggle value is inverted. - Returns:~ - Current value of |gitsigns-config-show_deleted| + Returns: ~ + (boolean): Current value of |gitsigns-config-show_deleted| toggle_current_line_blame({value}) *gitsigns.toggle_current_line_blame()* Toggle |gitsigns-config-current_line_blame| - Parameters:~ - {value} boolean|nil Value to set toggle. If `nil` - the toggle value is inverted. + Parameters: ~ + {value} (boolean|nil): Value to set toggle. If `nil` + the toggle value is inverted. - Returns:~ - Current value of |gitsigns-config-current_line_blame| + Returns: ~ + (boolean): Current value of |gitsigns-config-current_line_blame| toggle_word_diff({value}) *gitsigns.toggle_word_diff()* Toggle |gitsigns-config-word_diff| - Parameters:~ - {value} boolean|nil Value to set toggle. If `nil` - the toggle value is inverted. + Parameters: ~ + {value} (boolean|nil): Value to set toggle. If `nil` + the toggle value is inverted. - Returns:~ - Current value of |gitsigns-config-word_diff| + Returns: ~ + (boolean): Current value of |gitsigns-config-word_diff| toggle_linehl({value}) *gitsigns.toggle_linehl()* Toggle |gitsigns-config-linehl| - Parameters:~ - {value} boolean|nil Value to set toggle. If `nil` - the toggle value is inverted. + Parameters: ~ + {value} (boolean|nil): Value to set toggle. If `nil` + the toggle value is inverted. - Returns:~ - Current value of |gitsigns-config-linehl| + Returns: ~ + (boolean): Current value of |gitsigns-config-linehl| toggle_numhl({value}) *gitsigns.toggle_numhl()* Toggle |gitsigns-config-numhl| - Parameters:~ - {value} boolean|nil Value to set toggle. If `nil` - the toggle value is inverted. + Parameters: ~ + {value} (boolean|nil): Value to set toggle. If `nil` + the toggle value is inverted. + - Returns:~ - Current value of |gitsigns-config-numhl| + Returns: ~ + (boolean): Current value of |gitsigns-config-numhl| toggle_signs({value}) *gitsigns.toggle_signs()* Toggle |gitsigns-config-signbooleancolumn| - Parameters:~ - {value} boolean|nil Value to set toggle. If `nil` - the toggle value is inverted. + Parameters: ~ + {value} (boolean|nil): Value to set toggle. If `nil` + the toggle value is inverted. - Returns:~ - Current value of |gitsigns-config-signcolumn| + Returns: ~ + (boolean): Current value of |gitsigns-config-signcolumn| ============================================================================== diff --git a/gen_help.lua b/gen_help.lua index cc54e224..01ccd90b 100755 --- a/gen_help.lua +++ b/gen_help.lua @@ -5,20 +5,13 @@ exec nvim -l "$0" "$@" -- Simple script to update the help doc by reading the config schema. local inspect = vim.inspect -local config = require('lua.gitsigns.config') +local list_extend = vim.list_extend +local startswith = vim.startswith -function table.slice(tbl, first, last, step) - local sliced = {} - for i = first or 1, last or #tbl, step or 1 do - sliced[#sliced+1] = tbl[i] - end - return sliced -end - -local function startswith(str, start) - return str.sub(str, 1, string.len(start)) == start -end +local config = require('lua.gitsigns.config') +--- @param path string +--- @return string local function read_file(path) local f = assert(io.open(path, 'r')) local t = f:read("*all") @@ -163,42 +156,209 @@ local function parse_func_header(line) ) end +--- @param x string +--- @return string? name +--- @return string? type +--- @return string? description +local function parse_param(x) + local name, ty, des = x:match('([^ ]+) +([^ ]+) *(.*)') + return name, ty, des +end + +--- @param x string[] +--- @return string[] +local function trim_lines(x) + local min_pad --- @type integer? + for _, e in ipairs(x) do + local _, i = e:find('^ *') + if not min_pad or min_pad > i then + min_pad = i + end + end + + local r = {} --- @type string[] + for _, e in ipairs(x) do + r[#r+1] = e:sub(min_pad + 1) + end + + return r +end + +--- @param name string +--- @param ty string +--- @param desc string[] +--- @param name_pad? integer +--- @return string[] +local function render_param_or_return(name, ty, desc, name_pad) + name_pad = name_pad and (name_pad + 3) or 0 + local name_str --- @type string + + if name == ':' then + name_str = '' + else + local nf = '%-'..tostring(name_pad)..'s' + name_str = nf:format(string.format('{%s} ', name)) + end + + if #desc == 0 then + return { string.format(' %s(%s)', name_str, ty) } + end + + local r = {} --- @type string[] + + local desc1 = desc[1] == '' and '' or ' '..desc[1] + r[#r+1] = string.format(' %s(%s): %s', name_str, ty, desc1) + + local remain_desc = trim_lines(vim.list_slice(desc, 2)) + for _, d in ipairs(remain_desc) do + r[#r+1] = ' '..string.rep(' ', name_pad)..d + end + + return r +end + +--- @param x string[] +--- @param amount integer +--- @return string[] +local function pad(x, amount) + local pad_str = string.rep(' ', amount) + + local r = {} --- @type string[] + for _, e in ipairs(x) do + r[#r+1] = pad_str..e + end + return r +end + +--- @param state EmmyState +--- @param doc_comment string +--- @param desc string[] +--- @param params {[1]: string, [2]: string, [3]: string[]}[] +--- @param returns {[1]: string, [2]: string, [3]: string[]}[] +--- @return EmmyState +local function process_doc_comment(state, doc_comment, desc, params, returns) + if state == 'none' then + state = 'in_block' + end + + local emmy_type, emmy_str = doc_comment:match(' ?@([a-z]+) (.*)') + + if emmy_type == 'param' then + local name, ty, pdesc = parse_param(emmy_str) + params[#params+1] = {name, ty, { pdesc }} + return 'in_param' + end + + if emmy_type == 'return' then + local ty, name, rdesc = parse_param(emmy_str) + returns[#returns+1] = {name, ty, { rdesc }} + return 'in_return' + end + + if state == 'in_param' then + -- Consume any remaining doc document lines as the description for the + -- last parameter + local lastdes = params[#params][3] + lastdes[#lastdes+1] = doc_comment + elseif state == 'in_return' then + -- Consume any remaining doc document lines as the description for the + -- last return + local lastdes = returns[#returns][3] + lastdes[#lastdes+1] = doc_comment + else + if doc_comment ~= '' and doc_comment ~= '<' then + doc_comment = string.rep(' ', 16)..doc_comment + end + desc[#desc+1] = doc_comment + end + + return state +end + +--- @param header string +--- @param block string[] +--- @param params {[1]: string, [2]: string, [3]: string[]}[] +--- @param returns {[1]: string, [2]: string, [3]: string[]}[] +--- @return string[] +local function render_block(header, block, params, returns) + local res = { header } + list_extend(res, block) + + -- filter arguments beginning with '_' + params = vim.tbl_filter( + --- @param v {[1]: string, [2]: string, [3]: string[]} + --- @return boolean + function(v) + return not startswith(v[1], '_') + end, + params + ) + + if #params > 0 then + local param_block = {'Parameters: ~'} + + local name_pad = 0 + for _, v in ipairs(params) do + if #v[1] > name_pad then + name_pad = #v[1] + end + end + + for _, v in ipairs(params) do + local name, ty, desc = v[1], v[2], v[3] + list_extend(param_block, render_param_or_return(name, ty, desc, name_pad)) + end + list_extend(res, pad(param_block, 16)) + end + + if #returns > 0 then + res[#res+1] = '' + local param_block = {'Returns: ~'} + for _, v in ipairs(returns) do + local name, ty, desc = v[1], v[2], v[3] + list_extend(param_block, render_param_or_return(name, ty, desc)) + end + list_extend(res, pad(param_block, 16)) + end + + return res +end + --- @param path string --- @return string local function gen_functions_doc_from_file(path) - local i = read_file(path):gmatch("([^\n]*)\n?") + local i = read_file(path):gmatch("([^\n]*)\n?") --- @type Iterator[string] + + local blocks = {} --- @type string[][] - local res = {} - local blocks = {} - local block = {''} + --- @alias EmmyState 'none'|'in_block'|'in_param'|'in_return' + local state = 'none' --- @type EmmyState + local desc = {} --- @type string[] + local params = {} --- @type {[1]: string, [2]: string, [3]: string[]}[] + local returns = {} --- @type {[1]: string, [2]: string, [3]: string[]}[] - local in_block = false for l in i do - local l1 = l:match('^%-%-%- ?(.*)') - if l1 then - in_block = true - if l1 ~= '' and l1 ~= '<' then - l1 = ' '..l1 + local doc_comment = l:match('^%-%-%- ?(.*)') --- @type string? + if doc_comment then + state = process_doc_comment(state, doc_comment, desc, params, returns) + elseif state ~= 'none' then + -- First line after block + local ok, header = pcall(parse_func_header, l) + if ok then + blocks[#blocks+1] = render_block(header, desc, params, returns) end - block[#block+1] = l1 - else - if in_block then - -- First line after block - local ok, header = pcall(parse_func_header, l) - if ok then - block[1] = header - blocks[#blocks+1] = block - end - block = {''} - end - in_block = false + state = 'none' + desc = {} + params = {} + returns = {} end end + local res = {} --- @type string[] for j = #blocks, 1, -1 do local b = blocks[j] for k = 1, #b do - res[#res+1] = b[k] + res[#res+1] = b[k]:match('^ *$') and '' or b[k] end res[#res+1] = '' end @@ -254,19 +414,21 @@ end --- @return string local function get_setup_from_readme() - local i = read_file('README.md'):gmatch("([^\n]*)\n?") + local readme = read_file('README.md'):gmatch("([^\n]*)\n?") --- @type Iterator local res = {} --- @type string[] + local function append(line) res[#res+1] = line ~= '' and ' '..line or '' end - for l in i do + + for l in readme do if l:match("require%('gitsigns'%).setup {") then append(l) break end end - for l in i do + for l in readme do append(l) if l == '}' then break @@ -276,6 +438,8 @@ local function get_setup_from_readme() return table.concat(res, '\n') end +--- @param marker string +--- @return string|fun():string local function get_marker_text(marker) return ({ VERSION = '0.7-dev', @@ -293,11 +457,11 @@ local function get_marker_text(marker) end local function main() - local i = read_file('etc/doc_template.txt'):gmatch("([^\n]*)\n?") + local template = read_file('etc/doc_template.txt'):gmatch("([^\n]*)\n?") --- @type Iterator - local out = io.open('doc/gitsigns.txt', 'w') + local out = assert(io.open('doc/gitsigns.txt', 'w')) - for l in i do + for l in template do local marker = l:match('{{(.*)}}') if marker then local sub = get_marker_text(marker) diff --git a/lua/gitsigns.lua b/lua/gitsigns.lua index 043ed59a..d2756c0d 100644 --- a/lua/gitsigns.lua +++ b/lua/gitsigns.lua @@ -154,9 +154,8 @@ end --- Attributes: ~ --- {async} --- ---- Parameters: ~ ---- {cfg} Table object containing configuration for ---- Gitsigns. See |gitsigns-usage| for more details. +--- @param cfg table Configuration for Gitsigns. +--- See |gitsigns-usage| for more details. M.setup = void(function(cfg) gs_config.build(cfg) diff --git a/lua/gitsigns/actions.lua b/lua/gitsigns/actions.lua index 0b5a0024..3e351bb0 100644 --- a/lua/gitsigns/actions.lua +++ b/lua/gitsigns/actions.lua @@ -48,12 +48,9 @@ end --- Toggle |gitsigns-config-signbooleancolumn| --- ---- Parameters:~ ---- {value} boolean|nil Value to set toggle. If `nil` +--- @param value boolean|nil Value to set toggle. If `nil` --- the toggle value is inverted. ---- ---- Returns:~ ---- Current value of |gitsigns-config-signcolumn| +--- @return boolean : Current value of |gitsigns-config-signcolumn| M.toggle_signs = function(value) if value ~= nil then config.signcolumn = value @@ -66,12 +63,10 @@ end --- Toggle |gitsigns-config-numhl| --- ---- Parameters:~ ---- {value} boolean|nil Value to set toggle. If `nil` +--- @param value boolean|nil Value to set toggle. If `nil` --- the toggle value is inverted. --- ---- Returns:~ ---- Current value of |gitsigns-config-numhl| +--- @return boolean : Current value of |gitsigns-config-numhl| M.toggle_numhl = function(value) if value ~= nil then config.numhl = value @@ -84,12 +79,9 @@ end --- Toggle |gitsigns-config-linehl| --- ---- Parameters:~ ---- {value} boolean|nil Value to set toggle. If `nil` +--- @param value boolean|nil Value to set toggle. If `nil` --- the toggle value is inverted. ---- ---- Returns:~ ---- Current value of |gitsigns-config-linehl| +--- @return boolean : Current value of |gitsigns-config-linehl| M.toggle_linehl = function(value) if value ~= nil then config.linehl = value @@ -102,12 +94,9 @@ end --- Toggle |gitsigns-config-word_diff| --- ---- Parameters:~ ---- {value} boolean|nil Value to set toggle. If `nil` +--- @param value boolean|nil Value to set toggle. If `nil` --- the toggle value is inverted. ---- ---- Returns:~ ---- Current value of |gitsigns-config-word_diff| +--- @return boolean : Current value of |gitsigns-config-word_diff| M.toggle_word_diff = function(value) if value ~= nil then config.word_diff = value @@ -121,12 +110,9 @@ end --- Toggle |gitsigns-config-current_line_blame| --- ---- Parameters:~ ---- {value} boolean|nil Value to set toggle. If `nil` +--- @param value boolean|nil Value to set toggle. If `nil` --- the toggle value is inverted. ---- ---- Returns:~ ---- Current value of |gitsigns-config-current_line_blame| +--- @return boolean : Current value of |gitsigns-config-current_line_blame| M.toggle_current_line_blame = function(value) if value ~= nil then config.current_line_blame = value @@ -139,12 +125,9 @@ end --- Toggle |gitsigns-config-show_deleted| --- ---- Parameters:~ ---- {value} boolean|nil Value to set toggle. If `nil` +--- @param value boolean|nil Value to set toggle. If `nil` --- the toggle value is inverted. ---- ---- Returns:~ ---- Current value of |gitsigns-config-show_deleted| +--- @return boolean : Current value of |gitsigns-config-show_deleted| M.toggle_deleted = function(value) if value ~= nil then config.show_deleted = value @@ -251,16 +234,14 @@ end --- Attributes: ~ --- {async} --- ---- Parameters:~ ---- {range} table|nil List-like table of two integers making +--- @param range table|nil List-like table of two integers making --- up the line range from which you want to stage the hunks. --- If running via command line, then this is taken from the --- command modifiers. ---- {opts} table|nil Additional options: +--- @param opts table|nil Additional options: --- • {greedy}: (boolean) --- Stage all contiguous hunks. Only useful if 'diff_opts' --- contains `linematch`. Defaults to `true`. ---- M.stage_hunk = mk_repeatable(void(function(range, opts) opts = opts or {} local bufnr = current_buf() @@ -304,16 +285,14 @@ end --- meaning if a range only includes a portion of a particular --- hunk, only the lines within the range will be reset. --- ---- Parameters:~ ---- {range} table|nil List-like table of two integers making ---- up the line range from which you want to reset the hunks. ---- If running via command line, then this is taken from the ---- command modifiers. ---- {opts} table|nil Additional options: ---- • {greedy}: (boolean) ---- Stage all contiguous hunks. Only useful if 'diff_opts' ---- contains `linematch`. Defaults to `true`. ---- +--- @param range table|nil List-like table of two integers making +--- up the line range from which you want to reset the hunks. +--- If running via command line, then this is taken from the +--- command modifiers. +--- @param opts table|nil Additional options: +--- • {greedy}: (boolean) +--- Stage all contiguous hunks. Only useful if 'diff_opts' +--- contains `linematch`. Defaults to `true`. M.reset_hunk = mk_repeatable(void(function(range, opts) opts = opts or {} local bufnr = current_buf() @@ -540,24 +519,23 @@ end) --- (popup or inline) was previously opened, it will be re-opened --- at the next hunk. --- ---- Parameters: ~ ---- {opts} table|nil Configuration table. Keys: ---- • {wrap}: (boolean) ---- Whether to loop around file or not. Defaults ---- to the value 'wrapscan' ---- • {navigation_message}: (boolean) ---- Whether to show navigation messages or not. ---- Looks at 'shortmess' for default behaviour. ---- • {foldopen}: (boolean) ---- Expand folds when navigating to a hunk which is ---- inside a fold. Defaults to `true` if 'foldopen' ---- contains `search`. ---- • {preview}: (boolean) ---- Automatically open preview_hunk() upon navigating ---- to a hunk. ---- • {greedy}: (boolean) ---- Only navigate between non-contiguous hunks. Only useful if ---- 'diff_opts' contains `linematch`. Defaults to `true`. +--- @param opts table|nil Configuration table. Keys: +--- • {wrap}: (boolean) +--- Whether to loop around file or not. Defaults +--- to the value 'wrapscan' +--- • {navigation_message}: (boolean) +--- Whether to show navigation messages or not. +--- Looks at 'shortmess' for default behaviour. +--- • {foldopen}: (boolean) +--- Expand folds when navigating to a hunk which is +--- inside a fold. Defaults to `true` if 'foldopen' +--- contains `search`. +--- • {preview}: (boolean) +--- Automatically open preview_hunk() upon navigating +--- to a hunk. +--- • {greedy}: (boolean) +--- Only navigate between non-contiguous hunks. Only useful if +--- 'diff_opts' contains `linematch`. Defaults to `true`. M.next_hunk = function(opts) opts = opts or {} opts.forwards = true @@ -759,24 +737,22 @@ end --- Get hunk array for specified buffer. --- ---- Parameters: ~ ---- {bufnr} integer: Buffer number, if not provided (or 0) +--- @param bufnr integer Buffer number, if not provided (or 0) --- will use current buffer. ---- ---- Return: ~ ---- Array of hunk objects. Each hunk object has keys: ---- • `"type"`: String with possible values: "add", "change", ---- "delete" ---- • `"head"`: Header that appears in the unified diff ---- output. ---- • `"lines"`: Line contents of the hunks prefixed with ---- either `"-"` or `"+"`. ---- • `"removed"`: Sub-table with fields: ---- • `"start"`: Line number (1-based) ---- • `"count"`: Line count ---- • `"added"`: Sub-table with fields: ---- • `"start"`: Line number (1-based) ---- • `"count"`: Line count +--- @return table|nil : Array of hunk objects. +--- Each hunk object has keys: +--- • `"type"`: String with possible values: "add", "change", +--- "delete" +--- • `"head"`: Header that appears in the unified diff +--- output. +--- • `"lines"`: Line contents of the hunks prefixed with +--- either `"-"` or `"+"`. +--- • `"removed"`: Sub-table with fields: +--- • `"start"`: Line number (1-based) +--- • `"count"`: Line count +--- • `"added"`: Sub-table with fields: +--- • `"start"`: Line number (1-based) +--- • `"count"`: Line count M.get_hunks = function(bufnr) bufnr = bufnr or current_buf() if not cache[bufnr] then @@ -844,16 +820,14 @@ end --- floating window. If already open, calling this will cause the --- window to get focus. --- ---- Parameters: ~ ---- {opts} (table|nil): ---- Additional options: ---- • {full}: (boolean) ---- Display full commit message with hunk. ---- • {ignore_whitespace}: (boolean) ---- Ignore whitespace when running blame. ---- --- Attributes: ~ --- {async} +--- +--- @param opts table|nil Additional options: +--- • {full}: (boolean) +--- Display full commit message with hunk. +--- • {ignore_whitespace}: (boolean) +--- Ignore whitespace when running blame. M.blame_line = void(function(opts) if popup.focus_open('blame') then return @@ -917,10 +891,6 @@ end --- Attributes: ~ --- {async} --- ---- Parameters:~ ---- {base} string|nil The object/revision to diff against. ---- {global} boolean|nil Change the base of all buffers. ---- --- Examples: > --- " Change base to 1 commit behind head --- :lua require('gitsigns').change_base('HEAD~1') @@ -942,6 +912,9 @@ end --- --- For a more complete list of ways to specify bases, see --- |gitsigns-revision|. +--- +--- @param base string|nil The object/revision to diff against. +--- @param global boolean|nil Change the base of all buffers. M.change_base = void(function(base, global) base = util.calc_base(base) @@ -986,19 +959,6 @@ end --- If {base} is the index, then the opened buffer is editable and --- any written changes will update the index accordingly. --- ---- Parameters: ~ ---- {base} (string|nil): Revision to diff against. Defaults ---- to index. ---- {opts} (table|nil): ---- Additional options: ---- • {vertical}: {boolean}. Split window vertically. Defaults to ---- config.diff_opts.vertical. If running via command line, then ---- this is taken from the command modifiers. ---- • {split}: {string}. One of: 'aboveleft', 'belowright', ---- 'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to ---- 'aboveleft'. If running via command line, then this is taken ---- from the command modifiers. ---- --- Examples: > --- " Diff against the index --- :Gitsigns diffthis @@ -1012,6 +972,16 @@ end --- --- Attributes: ~ --- {async} +--- +--- @param base string|nil Revision to diff against. Defaults to index. +--- @param opts table|nil Additional options: +--- • {vertical}: {boolean}. Split window vertically. Defaults to +--- config.diff_opts.vertical. If running via command line, then +--- this is taken from the command modifiers. +--- • {split}: {string}. One of: 'aboveleft', 'belowright', +--- 'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to +--- 'aboveleft'. If running via command line, then this is taken +--- from the command modifiers. M.diffthis = function(base, opts) -- TODO(lewis6991): can't pass numbers as strings from the command line if base ~= nil then @@ -1147,28 +1117,26 @@ end --- Attributes: ~ --- {async} --- ---- Parameters: ~ ---- {target} (integer or string): ---- Specifies which files hunks are collected from. ---- Possible values. ---- • [integer]: The buffer with the matching buffer ---- number. `0` for current buffer (default). ---- • `"attached"`: All attached buffers. ---- • `"all"`: All modified files for each git ---- directory of all attached buffers in addition ---- to the current working directory. ---- {opts} (table|nil): ---- Additional options: ---- • {use_location_list}: (boolean) ---- Populate the location list instead of the ---- quickfix list. Default to `false`. ---- • {nr}: (integer) ---- Window number or ID when using location list. ---- Expand folds when navigating to a hunk which is ---- inside a fold. Defaults to `0`. ---- • {open}: (boolean) ---- Open the quickfix/location list viewer. ---- Defaults to `true`. +--- @param target integer|string +--- Specifies which files hunks are collected from. +--- Possible values. +--- • [integer]: The buffer with the matching buffer +--- number. `0` for current buffer (default). +--- • `"attached"`: All attached buffers. +--- • `"all"`: All modified files for each git +--- directory of all attached buffers in addition +--- to the current working directory. +--- @param opts table|nil Additional options: +--- • {use_location_list}: (boolean) +--- Populate the location list instead of the +--- quickfix list. Default to `false`. +--- • {nr}: (integer) +--- Window number or ID when using location list. +--- Expand folds when navigating to a hunk which is +--- inside a fold. Defaults to `0`. +--- • {open}: (boolean) +--- Open the quickfix/location list viewer. +--- Defaults to `true`. M.setqflist = void(function(target, opts) opts = opts or {} if opts.open == nil then @@ -1209,10 +1177,9 @@ end) --- Attributes: ~ --- {async} --- ---- Parameters: ~ ---- {nr} (integer): Window number or the |window-ID|. ---- `0` for the current window (default). ---- {target} (integer or string): See |gitsigns.setqflist()|. +--- @param nr integer Window number or the |window-ID|. +--- `0` for the current window (default). +--- @param target integer|string See |gitsigns.setqflist()|. M.setloclist = function(nr, target) M.setqflist(target, { nr = nr, @@ -1223,8 +1190,7 @@ end --- Get all the available line specific actions for the current --- buffer at the cursor position. --- ---- Return: ~ ---- Dictionary of action name to function which when called +--- @return table|nil : Dictionary of action name to function which when called --- performs action. M.get_actions = function() local bufnr = current_buf() diff --git a/lua/gitsigns/attach.lua b/lua/gitsigns/attach.lua index 7f22c10c..48fb60d5 100644 --- a/lua/gitsigns/attach.lua +++ b/lua/gitsigns/attach.lua @@ -105,6 +105,7 @@ local function on_lines(_, bufnr, _, first, last_orig, last_new, byte_count) return manager.on_lines(bufnr, first, last_orig, last_new) end +--- @param _ 'reload' --- @param bufnr integer local function on_reload(_, bufnr) local __FUNC__ = 'on_reload' @@ -112,6 +113,7 @@ local function on_reload(_, bufnr) manager.update_debounced(bufnr) end +--- @param _ 'detach' --- @param bufnr integer local function on_detach(_, bufnr) M.detach(bufnr, true) @@ -371,8 +373,8 @@ end --- Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not --- provided then the current buffer is used. --- ---- Parameters: ~ ---- {bufnr} (number): Buffer number +--- @param bufnr integer Buffer number +--- @param _keep_signs? boolean function M.detach(bufnr, _keep_signs) -- When this is called interactively (with no arguments) we want to remove all -- the signs, however if called via a detach event (due to nvim_buf_attach) @@ -401,23 +403,22 @@ end --- Attributes: ~ --- {async} --- ---- Parameters: ~ ---- {bufnr} (number): Buffer number ---- {ctx} (table|nil): ---- Git context data that may optionally be used to attach to any ---- buffer that represents a real git object. ---- • {file}: (string) ---- Path to the file represented by the buffer, relative to the ---- top-level. ---- • {toplevel}: (string) ---- Path to the top-level of the parent git repository. ---- • {gitdir}: (string) ---- Path to the git directory of the parent git repository ---- (typically the ".git/" directory). ---- • {commit}: (string) ---- The git revision that the file belongs to. ---- • {base}: (string|nil) ---- The git revision that the file should be compared to. +--- @param bufnr integer Buffer number +--- @param ctx table|nil +--- Git context data that may optionally be used to attach to any +--- buffer that represents a real git object. +--- • {file}: (string) +--- Path to the file represented by the buffer, relative to the +--- top-level. +--- • {toplevel}: (string) +--- Path to the top-level of the parent git repository. +--- • {gitdir}: (string) +--- Path to the git directory of the parent git repository +--- (typically the ".git/" directory). +--- • {commit}: (string) +--- The git revision that the file belongs to. +--- • {base}: (string|nil) +--- The git revision that the file should be compared to. M.attach = void(function(bufnr, ctx, _trigger) attach_throttled(bufnr or api.nvim_get_current_buf(), ctx, _trigger) end)