refactor(docs): remove unnecessary @private/@nodoc annotations (#33951)

* refactor(docs): remove `@private` annotations from local functions

* refactor(docs): remove unnecessary `@nodoc` annotations

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

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

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

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.

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

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)

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

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)

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

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

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,

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

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', ...)