doc: fix scripts and regenerate (#12506)

* Fix some small doc issues

* doc: fixup

* doc: fixup

* Fix lint and rebase

* Remove bad advice

* Ugh, stupid mpack files...

* Don't let people include these for now until they specifically want to

* Prevent duplicate tag

runtime/lua/vim/lsp/buf.lua

@@ -23,6 +23,9 @@ local function request(method, params, callback)
   return vim.lsp.buf_request(0, method, params, callback)
 end
 
+--- Sends a notification through all clients associated with current buffer.
+--
+--@return `true` if server responds.
 function M.server_ready()
   return not not vim.lsp.buf_notify(0, "window/progress", {})
 end
@@ -69,6 +72,10 @@ function M.formatting(options)
   return request('textDocument/formatting', params)
 end
 
+--- Perform |vim.lsp.buf.formatting()| synchronously.
+---
+--- Useful for running on save, to make sure buffer is formatted prior to being
+--- saved.  {timeout_ms} is passed on to |vim.lsp.buf_request_sync()|.
 function M.formatting_sync(options, timeout_ms)
   local params = util.make_formatting_params(options)
   local result = vim.lsp.buf_request_sync(0, "textDocument/formatting", params, timeout_ms)
@@ -136,6 +143,12 @@ function M.document_symbol()
   request('textDocument/documentSymbol', params)
 end
 
+
+--- Lists all symbols in the current workspace in the quickfix window.
+---
+--- The list is filtered against the optional argument {query};
+--- if the argument is omitted from the call, the user is prompted to enter a string on the command line.
+--- An empty string means no filtering is done.
 function M.workspace_symbol(query)
   query = query or npcall(vfn.input, "Query: ")
   local params = {query = query}

runtime/lua/vim/lsp/rpc.lua

@@ -36,10 +36,12 @@ end
 --- Merges current process env with the given env and returns the result as
 --- a list of "k=v" strings.
 ---
+--- <pre>
 --- Example:
 ---
----      { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
----   => { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
+---  in:    { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
+---  out:   { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
+--- </pre>
 local function env_merge(env)
   if env == nil then
     return env

runtime/lua/vim/lsp/util.lua

@@ -952,7 +952,9 @@ do
   end
 
   --- Saves the diagnostics (Diagnostic[]) into diagnostics_by_buf
-  --
+  ---
+  --@param bufnr bufnr for which the diagnostics are for.
+  --@param diagnostics Diagnostics[] received from the language server.
   function M.buf_diagnostics_save_positions(bufnr, diagnostics)
     validate {
       bufnr = {bufnr, 'n', true};
@@ -1044,6 +1046,29 @@ do
     end
   end
 
+  --- Returns the number of diagnostics of given kind for current buffer.
+  ---
+  --- Useful for showing diagnostic counts in statusline. eg:
+  ---
+  --- <pre>
+  --- function! LspStatus() abort
+  ---     let sl = ''
+  ---     if luaeval('not vim.tbl_isempty(vim.lsp.buf_get_clients(0))')
+  ---         let sl.='%#MyStatuslineLSP#E:'
+  ---         let sl.='%#MyStatuslineLSPErrors#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Error]])")}'
+  ---         let sl.='%#MyStatuslineLSP# W:'
+  ---         let sl.='%#MyStatuslineLSPWarnings#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Warning]])")}'
+  ---     else
+  ---         let sl.='%#MyStatuslineLSPErrors#off'
+  ---     endif
+  ---     return sl
+  --- endfunction
+  --- let &l:statusline = '%#MyStatuslineLSP#LSP '.LspStatus()
+  --- </pre>
+  ---
+  --@param kind Diagnostic severity kind: See |vim.lsp.protocol.DiagnosticSeverity|
+  ---
+  --@return Count of diagnostics
   function M.buf_diagnostics_count(kind)
     local bufnr = vim.api.nvim_get_current_buf()
     local diagnostics = M.diagnostics_by_buf[bufnr]
@@ -1064,6 +1089,16 @@ do
     [protocol.DiagnosticSeverity.Hint] = "LspDiagnosticsHintSign";
   }
 
+  --- Place signs for each diagnostic in the sign column.
+  ---
+  --- Sign characters can be customized with the following commands:
+  ---
+  --- <pre>
+  --- sign define LspDiagnosticsErrorSign text=E texthl=LspDiagnosticsError linehl= numhl=
+  --- sign define LspDiagnosticsWarningSign text=W texthl=LspDiagnosticsWarning linehl= numhl=
+  --- sign define LspDiagnosticsInformationSign text=I texthl=LspDiagnosticsInformation linehl= numhl=
+  --- sign define LspDiagnosticsHintSign text=H texthl=LspDiagnosticsHint linehl= numhl=
+  --- </pre>
   function M.buf_diagnostics_signs(bufnr, diagnostics)
     for _, diagnostic in ipairs(diagnostics) do
       vim.fn.sign_place(0, sign_ns, diagnostic_severity_map[diagnostic.severity], bufnr, {lnum=(diagnostic.range.start.line+1)})
@@ -1142,7 +1177,7 @@ end
 
 --- Convert symbols to quickfix list items
 ---
---@symbols DocumentSymbol[] or SymbolInformation[]
+--@param symbols DocumentSymbol[] or SymbolInformation[]
 function M.symbols_to_items(symbols, bufnr)
   local function _symbols_to_items(_symbols, _items, _bufnr)
     for _, symbol in ipairs(_symbols) do