lsp: vim.lsp.diagnostic (#12655)

Breaking Changes:
- Deprecated all `vim.lsp.util.{*diagnostics*}()` functions.
    - Instead, all functions must be found in vim.lsp.diagnostic
    - For now, they issue a warning ONCE per neovim session. In a
      "little while" we will remove them completely.
- `vim.lsp.callbacks` has moved to `vim.lsp.handlers`.
    - For a "little while" we will just redirect `vim.lsp.callbacks` to
      `vim.lsp.handlers`. However, we will remove this at some point, so
      it is recommended that you change all of your references to
      `callbacks` into `handlers`.
    - This also means that for functions like |vim.lsp.start_client()|
      and similar, keyword style arguments have moved from "callbacks"
      to "handlers". Once again, these are currently being forward, but
      will cease to be forwarded in a "little while".
- Changed the highlight groups for LspDiagnostic highlight as they were
  inconsistently named.
    - For more information, see |lsp-highlight-diagnostics|
- Changed the sign group names as well, to be consistent with
  |lsp-highlight-diagnostics|

General Enhancements:
- Rewrote much of the getting started help document for lsp. It also
  provides a much nicer configuration strategy, so as to not recommend
  globally overwriting builtin neovim mappings.

LSP Enhancements:
- Introduced the concept of |lsp-handlers| which will allow much better
  customization for users without having to copy & paste entire files /
  functions / etc.

Diagnostic Enhancements:
- "goto next diagnostic" |vim.lsp.diagnostic.goto_next()|
- "goto prev diagnostic" |vim.lsp.diagnostic.goto_prev()|
    - For each of the gotos, auto open diagnostics is available as a
      configuration option
- Configurable diagnostic handling:
    - See |vim.lsp.diagnostic.on_publish_diagnostics()|
    - Delay display until after insert mode
    - Configure signs
    - Configure virtual text
    - Configure underline
- Set the location list with the buffers diagnostics.
    - See |vim.lsp.diagnostic.set_loclist()|
- Better performance for getting counts and line diagnostics
    - They are now cached on save, to enhance lookups.
    - Particularly useful for checking in statusline, etc.
- Actual testing :)
    - See ./test/functional/plugin/lsp/diagnostic_spec.lua
- Added `guisp` for underline highlighting

NOTE: "a little while" means enough time to feel like most plugins and
plugin authors have had a chance to refactor their code to use the
updated calls. Then we will remove them completely. There is no need to
keep them, because we don't have any released version of neovim that
exposes these APIs. I'm trying to be nice to people following HEAD :)

Co-authored: [Twitch Chat 2020](https://twitch.tv/teej_dv)

scripts/lua2dox.lua

@@ -73,7 +73,7 @@ function class(BaseClass, ClassInitialiser)
     local newInstance = {}
     setmetatable(newInstance,newClass)
     --if init then
-    --	init(newInstance,...)
+    --  init(newInstance,...)
     if class_tbl.init then
       class_tbl.init(newInstance,...)
     else 
@@ -214,7 +214,7 @@ TStream_Read = class()
 --! \brief get contents of file
 --! 
 --! \param Filename name of file to read (or nil == stdin)
-function 	TStream_Read.getContents(this,Filename)
+function    TStream_Read.getContents(this,Filename)
   -- get lines from file
   local filecontents
   if Filename then
@@ -365,7 +365,7 @@ end
 --! \brief check comment for fn
 local function checkComment4fn(Fn_magic,MagicLines)
   local fn_magic = Fn_magic
-  --	TCore_IO_writeln('// checkComment4fn "' .. MagicLines .. '"')
+  --    TCore_IO_writeln('// checkComment4fn "' .. MagicLines .. '"')
 
   local magicLines = string_split(MagicLines,'\n')
 
@@ -375,7 +375,7 @@ local function checkComment4fn(Fn_magic,MagicLines)
     macro,tail = getMagicDirective(line)
     if macro == 'fn' then
       fn_magic = tail
-      --	TCore_IO_writeln('// found fn "' .. fn_magic .. '"')
+      --    TCore_IO_writeln('// found fn "' .. fn_magic .. '"')
     else
       --TCore_IO_writeln('// not found fn "' .. line .. '"')
     end
@@ -401,15 +401,23 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
     outStream:writelnTail('// #######################')
     outStream:writelnTail()
 
-    local state = ''
+    local state, offset = '', 0
     while not (err or inStream:eof()) do
       line = string_trim(inStream:getLine())
-      -- 			TCore_Debug_show_var('inStream',inStream)
-      -- 			TCore_Debug_show_var('line',line )
-      if string.sub(line,1,2)=='--' then -- it's a comment
-        if string.sub(line,3,3)=='@' then -- it's a magic comment
+      --            TCore_Debug_show_var('inStream',inStream)
+      --            TCore_Debug_show_var('line',line )
+      if string.sub(line,1,2) == '--' then -- it's a comment
+        -- Allow people to write style similar to EmmyLua (since they are basically the same)
+        -- instead of silently skipping things that start with ---
+        if string.sub(line, 3, 3) == '@' then -- it's a magic comment
+          offset = 0
+        elseif string.sub(line, 1, 4) == '---@' then -- it's a magic comment
+          offset = 1
+        end
+
+        if string.sub(line, 3, 3) == '@' or string.sub(line, 1, 4) == '---@' then -- it's a magic comment
           state = 'in_magic_comment'
-          local magic = string.sub(line,4)
+          local magic = string.sub(line, 4 + offset)
           outStream:writeln('/// @' .. magic)
           fn_magic = checkComment4fn(fn_magic,magic)
         elseif string.sub(line,3,3)=='-' then -- it's a nonmagic doc comment
@@ -450,7 +458,7 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
           outStream:writeln('// zz:"' .. line .. '"')
           fn_magic = nil
         end
-      elseif string.find(line,'^function') or string.find(line,'^local%s+function') then
+      elseif string.find(line, '^function') or string.find(line, '^local%s+function') then
         state = 'in_function'  -- it's a function
         local pos_fn = string.find(line,'function')
         -- function
@@ -490,6 +498,13 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
           this:warning(inStream:getLineNo(),'something weird here')
         end
         fn_magic = nil -- mustn't indavertently use it again
+
+      -- TODO: If we can make this learn how to generate these, that would be helpful.
+      -- elseif string.find(line, "^M%['.*'%] = function") then
+      --   state = 'in_function'  -- it's a function
+      --   outStream:writeln("function textDocument/publishDiagnostics(...){}")
+
+      --   fn_magic = nil -- mustn't indavertently use it again
       else
         state = ''  -- unknown
         if #line>0 then  -- we don't know what this line means, so just comment it out