docs: warnings on empty lists + docs on different modes

README.md

@@ -136,11 +136,20 @@ Trouble comes with the following defaults:
 
 Trouble comes with the following commands:
 
-* `LspTrouble [provider]`: open the list
-* `LspTroubleClose [provider]`: close the list
-* `LspTroubleToggle [provider]`: toggle the list
+* `LspTrouble [mode]`: open the list
+* `LspTroubleClose [mode]`: close the list
+* `LspTroubleToggle [mode]`: toggle the list
 * `LspTroubleRefresh`: manually refresh the active list
 
+Modes:
+
+* **lsp_document_diagnostics:** document diagnostics from the builtin LSP client
+* **lsp_workspace_diagnostics:** workspace diagnostics from the builtin LSP client
+* **lsp_references:** references of the word under the cursor from the builtin LSP client
+* **lsp_definitions:** definitions of the word under the cursor from the builtin LSP client
+* **quickfix:** [quickfix](https://neovim.io/doc/user/quickfix.html) items
+* **loclist:** items from the window's [location list](https://neovim.io/doc/user/quickfix.html)
+
 Example keybindings:
 
 ```vim

lua/trouble/providers/lsp.lua

@@ -11,7 +11,9 @@ function M.diagnostics(win, buf, cb, options)
     local buffer_diags = buf and {[buf] = vim.lsp.diagnostic.get(buf, nil)} or
                              vim.lsp.diagnostic.get_all()
 
-    cb(util.locations_to_items(buffer_diags, 1))
+    local items = util.locations_to_items(buffer_diags, 1)
+    if #items == 0 then util.warn("no diagnostics found") end
+    cb(items)
 end
 
 ---@return Item[]
@@ -25,6 +27,10 @@ function M.references(win, buf, cb, options)
             util.error("an error happened getting references: " .. err)
             return cb({})
         end
+        if result == nil or #result == 0 then
+            util.warn("No referenes found")
+            return cb({})
+        end
         local ret = util.locations_to_items({result}, 0)
         cb(ret)
     end)
@@ -42,8 +48,8 @@ function M.definitions(win, buf, cb, options)
             return cb({})
         end
         if result == nil or #result == 0 then
-           util.warn("No definitions found")
-           return cb({})
+            util.warn("No definitions found")
+            return cb({})
         end
         for _, value in ipairs(result) do
             value.uri = value.targetUri

lua/trouble/providers/qf.lua

@@ -26,6 +26,9 @@ function M.get_list(winid)
 
         table.insert(ret, util.process_item(pitem, item.bufnr))
     end
+    if #ret == 0 then
+        util.warn("the " .. (winid and "loclist" or "qflist") .. " is empty")
+    end
     return ret
 end
 

lua/trouble/providers/telescope.lua

@@ -1,11 +1,11 @@
+local util = require("trouble.util")
 local M = {}
 
 M.results = {}
 
 function M.open_with_trouble(prompt_bufnr, mode)
     local action_state = require('telescope.actions.state')
     local actions = require('telescope.actions')
-    local util = require("trouble.util")
     local picker = action_state.get_current_picker(prompt_bufnr)
     local manager = picker.manager
 
@@ -36,6 +36,12 @@ function M.open_with_trouble(prompt_bufnr, mode)
     require("trouble").open({mode = "telescope"})
 end
 
-function M.telescope(win, buf, cb, options) cb(M.results) end
+function M.telescope(win, buf, cb, options)
+    if #M.results == 0 then
+        util.warn(
+            "No Telescope results found. Open Telescopen and send results to Trouble first. Refer to the documentation for more info.")
+    end
+    cb(M.results)
+end
 
 return M