docs: make Lua docstrings consistent #15255

The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.

Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.

runtime/doc/develop.txt

@@ -191,8 +191,8 @@ definitions.  The |lua-vim| :help is generated from the docstrings.
 
 Docstring format:
 - Lines in the main description start with `---`
-- Special tokens start with `--@` followed by the token name:
-  `--@see`, `--@param`, `--@returns`
+- Special tokens start with `---@` followed by the token name:
+  `---@see`, `---@param`, `---@returns`
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>`  for code samples.
@@ -211,11 +211,11 @@ vim.paste in src/nvim/lua/vim.lua like this: >
     --- end)()
     --- </pre>
     ---
-    --@see |paste|
+    ---@see |paste|
     ---
-    --@param lines  ...
-    --@param phase  ...
-    --@returns false if client should cancel the paste.
+    ---@param lines  ...
+    ---@param phase  ...
+    ---@returns false if client should cancel the paste.
 
 
 LUA							*dev-lua*

runtime/doc/lsp.txt

@@ -1510,11 +1510,6 @@ reset({client_id}, {buffer_client_map})           *vim.lsp.diagnostic.reset()*
                     {buffer_client_map}  table map of buffers to active
                                          clients
 
-                                       *vim.lsp.diagnostic.restore_extmarks()*
-restore_extmarks({bufnr}, {last})
-                Parameters: ~
-                    {last}  number last line that was changed
-
 save({diagnostics}, {bufnr}, {client_id})          *vim.lsp.diagnostic.save()*
                 Save diagnostics to the current buffer.
 
@@ -1526,10 +1521,6 @@ save({diagnostics}, {bufnr}, {client_id})          *vim.lsp.diagnostic.save()*
                     {bufnr}        number
                     {client_id}    number
 
-                                          *vim.lsp.diagnostic.save_extmarks()*
-save_extmarks({bufnr}, {client_id})
-                TODO: Documentation
-
 set_loclist({opts})                         *vim.lsp.diagnostic.set_loclist()*
                 Sets the location list
 
@@ -1966,7 +1957,9 @@ diagnostics_to_items({diagnostics_by_bufnr}, {predicate})
                 Parameters: ~
                     {diagnostics_by_bufnr}  table bufnr -> Diagnostic []
                     {predicate}             an optional function to filter the
-                                            diagnostics.
+                                            diagnostics. If present, only
+                                            diagnostic items matching will be
+                                            included.
 
                 Return: ~
                     table (A list of items)
@@ -1999,6 +1992,8 @@ get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                     |softtabstop|
 
 get_line({uri}, {row})                               *vim.lsp.util.get_line()*
+                Gets the zero-indexed line from the given uri.
+
                 Parameters: ~
                     {uri}  string uri of the resource to get the line from
                     {row}  number zero-indexed line number
@@ -2007,6 +2002,8 @@ get_line({uri}, {row})                               *vim.lsp.util.get_line()*
                     string the line at row in filename
 
 get_lines({uri}, {rows})                            *vim.lsp.util.get_lines()*
+                Gets the zero-indexed lines from the given uri.
+
                 Parameters: ~
                     {uri}   string uri of the resource to get the lines from
                     {rows}  number[] zero-indexed line numbers
@@ -2014,9 +2011,6 @@ get_lines({uri}, {rows})                            *vim.lsp.util.get_lines()*
                 Return: ~
                     table<number string> a table mapping rows to lines
 
-get_markdown_fences()                     *vim.lsp.util.get_markdown_fences()*
-                TODO: Documentation
-
 get_progress_messages()                 *vim.lsp.util.get_progress_messages()*
                 TODO: Documentation
 
@@ -2197,6 +2191,8 @@ preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
                     or nil
 
 rename({old_fname}, {new_fname}, {opts})               *vim.lsp.util.rename()*
+                Rename old_fname to new_fname
+
                 Parameters: ~
                     {opts}  (table)
 

runtime/doc/lua.txt

@@ -1177,7 +1177,9 @@ make_dict_accessor({scope})                         *vim.make_dict_accessor()*
                 TODO: Documentation
 
 notify({msg}, {log_level}, {_opts})                             *vim.notify()*
-                Notification provider without a runtime, writes to :Messages
+                Notification provider
+
+                Without a runtime, writes to :Messages
 
                 Parameters: ~
                     {msg}        Content of the notification to show to the
@@ -1186,6 +1188,9 @@ notify({msg}, {log_level}, {_opts})                             *vim.notify()*
                     {opts}       Dictionary with optional options (timeout,
                                  etc)
 
+                See also: ~
+                    :help nvim_notify
+
 paste({lines}, {phase})                                          *vim.paste()*
                 Paste handler, invoked by |nvim_paste()| when a conforming UI
                 (such as the |TUI|) pastes text into the editor.