[LSP] Add in more docs for highlight groups with document_highlight() (#13614)

Currently it's not 100% clear that without setting these, using the autocomds
to utilize the `textDocument/documentHighlight` functionality, nothing will
actually be visible since the highlight groups don't have any details. This
just adds in a couple simple extra notes to make sure that's done

runtime/doc/lsp.txt

@@ -397,6 +397,11 @@ LSP HIGHLIGHT                                                    *lsp-highlight*
 
 Reference Highlights:
 
+Highlight groups that are meant to be used by |vim.lsp.buf.document_highlight()|.
+
+You can see more about the differences in types here:
+https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight
+
                                                            *hl-LspReferenceText*
 LspReferenceText          used for highlighting "text" references
                                                            *hl-LspReferenceRead*
@@ -932,15 +937,21 @@ definition()                                        *vim.lsp.buf.definition()*
                 Jumps to the definition of the symbol under the cursor.
 
 document_highlight()                        *vim.lsp.buf.document_highlight()*
-                Send request to server to resolve document highlights for the
+                Send request to the server to resolve document highlights for
-                current text document position. This request can be associated
+                the current text document position. This request can be
-                to key mapping or to events such as `CursorHold` , eg:
+                triggered by a key mapping or by events such as `CursorHold` ,
+                eg:
 >
     vim.api.nvim_command [[autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()]]
     vim.api.nvim_command [[autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()]]
     vim.api.nvim_command [[autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()]]
 <
 
+                Note: Usage of |vim.lsp.buf.document_highlight()| requires the
+                following highlight groups to be defined or you won't be able
+                to see the actual highlights. |LspReferenceText|
+                |LspReferenceRead| |LspReferenceWrite|
+
 document_symbol()                              *vim.lsp.buf.document_symbol()*
                 Lists all symbols in the current buffer in the quickfix
                 window.

runtime/lua/vim/lsp/buf.lua

@@ -310,15 +310,21 @@ function M.workspace_symbol(query)
   request('workspace/symbol', params)
 end
 
---- Send request to server to resolve document highlights for the
+--- Send request to the server to resolve document highlights for the current
---- current text document position. This request can be associated
+--- text document position. This request can be triggered by a  key mapping or
---- to key mapping or to events such as `CursorHold`, eg:
+--- by events such as `CursorHold`, eg:
 ---
 --- <pre>
 --- vim.api.nvim_command [[autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()]]
 --- vim.api.nvim_command [[autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()]]
 --- vim.api.nvim_command [[autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()]]
 --- </pre>
+---
+--- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups
+---       to be defined or you won't be able to see the actual highlights.
+---         |LspReferenceText|
+---         |LspReferenceRead|
+---         |LspReferenceWrite|
 function M.document_highlight()
   local params = util.make_position_params()
   request('textDocument/documentHighlight', params)