commit bee45fc0e7801396951cd156c82953cbadc256b9
parent 8605f5655bd8f52d1c4f259d39630b9140f07476
Author: Maria José Solano <majosolano99@gmail.com>
Date: Sat, 10 May 2025 16:42:48 -0500
refactor(docs): remove unnecessary `@private`/`@nodoc` annotations (#33951)
* refactor(docs): remove `@private` annotations from local functions
* refactor(docs): remove unnecessary `@nodoc` annotations
Diffstat:
13 files changed, 1 insertion(+), 25 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -299,7 +299,7 @@ types, etc. See [:help dev-lua-doc][dev-lua-doc].
- If possible, add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`.
- If a function in your Lua module should _not_ be documented, add `@nodoc`.
- If the function is internal or otherwise non-public add `@private`.
- - Private functions usually should be underscore-prefixed (named "_foo", not "foo").
+ - Private functions usually should be underscore-prefixed (named "_foo", not "foo"). Prefixing with an underscore implies `@nodoc`.
- Mark deprecated functions with `@deprecated`.
Third-party dependencies
diff --git a/runtime/lua/editorconfig.lua b/runtime/lua/editorconfig.lua
@@ -45,7 +45,6 @@
--- @type table<string,fun(bufnr: integer, val: string, opts?: table)>
local properties = {}
---- @private
--- Modified version of the builtin assert that does not include error position information
---
--- @param v any Condition
@@ -55,7 +54,6 @@ local function assert(v, message)
return v or error(message, 0)
end
---- @private
--- Show a warning message
--- @param msg string Message to show
local function warn(msg, ...)
@@ -211,7 +209,6 @@ function properties.spelling_language(bufnr, val)
end
end
---- @private
--- Modified version of [glob2regpat()] that does not match path separators on `*`.
---
--- This function replaces single instances of `*` with the regex pattern `[^/]*`.
@@ -233,7 +230,6 @@ local function glob2regpat(glob)
return (regpat:gsub(placeholder, '[^/]*'))
end
---- @private
--- Parse a single line in an EditorConfig file
--- @param line string Line
--- @return string? glob pattern if the line contains a pattern
@@ -256,7 +252,6 @@ local function parse_line(line)
end
end
---- @private
--- Parse options from an `.editorconfig` file
--- @param filepath string File path of the file to apply EditorConfig settings to
--- @param dir string Current directory
diff --git a/runtime/lua/vim/_comment.lua b/runtime/lua/vim/_comment.lua
@@ -1,4 +1,3 @@
----@nodoc
---@class vim._comment.Parts
---@field left string Left part of comment
---@field right string Right part of comment
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
@@ -923,8 +923,6 @@ function vim._expand_pat(pat, env)
local final_env = env
- --- @private
- ---
--- Allows submodules to be defined on a `vim.<module>` table without eager-loading the module.
---
--- Cmdline completion (`:lua vim.lsp.c<tab>`) accesses `vim.lsp._submodules` when no other candidates.
diff --git a/runtime/lua/vim/filetype/detect.lua b/runtime/lua/vim/filetype/detect.lua
@@ -1947,7 +1947,6 @@ local patterns_hashbang = {
['^vim\\>'] = { 'vim', { vim_regex = true } },
}
----@private
--- File starts with "#!".
--- @param contents string[]
--- @param path string
@@ -2140,7 +2139,6 @@ local patterns_text = {
['^#n$'] = 'sed',
}
----@private
--- File does not start with "#!".
--- @param contents string[]
--- @param path string
diff --git a/runtime/lua/vim/func.lua b/runtime/lua/vim/func.lua
@@ -35,7 +35,6 @@ local M = {}
--- @param fn F Function to memoize.
--- @param weak? boolean Use a weak table (default `true`)
--- @return F # Memoized version of {fn}
---- @nodoc
function M._memoize(hash, fn, weak)
-- this is wrapped in a function to lazily require the module
return require('vim.func._memoize')(hash, fn, weak)
diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua
@@ -328,7 +328,6 @@ function M.get_line_diagnostics(bufnr, line_nr, opts, client_id)
end
--- Clear diagnostics from pull based clients
---- @private
local function clear(bufnr)
for _, namespace in pairs(_client_pull_namespaces) do
vim.diagnostic.reset(namespace, bufnr)
@@ -337,7 +336,6 @@ end
--- Disable pull diagnostics for a buffer
--- @param bufnr integer
---- @private
local function disable(bufnr)
local bufstate = bufstates[bufnr]
if bufstate then
@@ -350,7 +348,6 @@ end
---@param bufnr integer buffer number
---@param client_id? integer Client ID to refresh (default: all clients)
---@param only_visible? boolean Whether to only refresh for the visible regions of the buffer (default: false)
----@private
local function _refresh(bufnr, client_id, only_visible)
if
only_visible
diff --git a/runtime/lua/vim/lsp/document_color.lua b/runtime/lua/vim/lsp/document_color.lua
@@ -231,7 +231,6 @@ local function buf_enable(bufnr)
M._buf_refresh(bufnr)
end
---- @nodoc
--- @param bufnr integer
--- @param client_id? integer
function M._buf_refresh(bufnr, client_id)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
@@ -476,8 +476,6 @@ RCS[ms.textDocument_documentHighlight] = function(_, result, ctx)
util.buf_highlight_references(ctx.bufnr, result, client.offset_encoding)
end
---- @private
----
--- Displays call hierarchy in the quickfix window.
---
--- @param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -231,7 +231,6 @@ end
--- Refresh inlay hints, only if we have attached clients that support it
---@param bufnr (integer) Buffer handle, or 0 for current
---@param opts? vim.lsp.util._refresh.Opts Additional options to pass to util._refresh
----@private
local function _refresh(bufnr, opts)
opts = opts or {}
opts['bufnr'] = bufnr
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
@@ -36,7 +36,6 @@ end
local M = {}
--- Mapping of error codes used by the client
---- @nodoc
local client_errors = {
INVALID_SERVER_MESSAGE = 1,
INVALID_SERVER_JSON = 2,
diff --git a/runtime/lua/vim/treesitter/_range.lua b/runtime/lua/vim/treesitter/_range.lua
@@ -25,7 +25,6 @@ local M = {}
---@alias Range Range2|Range4|Range6
----@private
---@param a_row integer
---@param a_col integer
---@param b_row integer
@@ -166,7 +165,6 @@ function M.contains(r1, r2)
return true
end
---- @private
--- @param source integer|string
--- @param index integer
--- @return integer
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
@@ -1164,7 +1164,6 @@ function LanguageTree:_edit(
end
end
----@nodoc
---@param bufnr integer
---@param changed_tick integer
---@param start_row integer
@@ -1236,12 +1235,10 @@ function LanguageTree:_on_bytes(
)
end
----@nodoc
function LanguageTree:_on_reload()
self:invalidate(true)
end
----@nodoc
function LanguageTree:_on_detach(...)
self:invalidate(true)
self:_do_callback('detach', ...)
