docs: docgen for API

README.md

@@ -258,7 +258,7 @@ Modes:
 
 - **diagnostics**: diagnostics
 - **diagnostics_buffer**: buffer diagnostics
-- **fs**: 
+- **fs**:
 - **loclist**: Location List
 - **lsp**: LSP definitions, references, implementations, type definitions, and declarations
 - **lsp_declarations**: declarations
@@ -280,29 +280,160 @@ Modes:
 
 You can use the following functions in your keybindings:
 
+<!-- api:start -->
+
 ```lua
--- toggle trouble with optional mode
-require("trouble").toggle(mode?)
+--- Finds all open views matching the filter.
+---@param opts? trouble.Config|string
+---@param filter? trouble.View.filter
+---@return trouble.View[], trouble.Config
+require("trouble").find(opts, filter)
+
+--- Finds the last open view matching the filter.
+---@param opts? trouble.Open|string
+---@param filter? trouble.View.filter
+---@return trouble.View?, trouble.Open
+require("trouble").find_last(opts, filter)
+
+--- Gets the last open view matching the filter or creates a new one.
+---@param opts? trouble.Config|string
+---@param filter? trouble.View.filter
+---@return trouble.View, trouble.Open
+require("trouble").get(opts, filter)
+
+---@param opts? trouble.Open|string
+require("trouble").open(opts)
+
+--- Returns true if there is an open view matching the filter.
+---@param opts? trouble.Config|string
+require("trouble").is_open(opts)
+
+---@param opts? trouble.Config|string
+require("trouble").close(opts)
+
+---@param opts? trouble.Open|string
+require("trouble").toggle(opts)
+
+--- Special case for refresh. Refresh all open views.
+---@param opts? trouble.Config|string
+require("trouble").refresh(opts)
+
+--- Proxy to last view's action.
+---@param action trouble.Action|string
+require("trouble").action(action)
+
+---@param opts? trouble.Config|string
+require("trouble").get_items(opts)
 
--- open trouble with optional mode
-require("trouble").open(mode?)
+---@param opts? trouble.Config|string
+---@return {get: fun():string, cond: fun():boolean}
+require("trouble").statusline(opts)
 
--- close trouble
+-- cancel
+require("trouble").cancel()
+
+-- close
 require("trouble").close()
 
--- jump to the next item, skipping the groups
-require("trouble").next({skip_groups = true, jump = true});
+-- first
+require("trouble").first()
+
+-- focus
+require("trouble").focus()
+
+-- Fold close
+require("trouble").fold_close()
+
+-- fold close all
+require("trouble").fold_close_all()
+
+-- Fold close recursive
+require("trouble").fold_close_recursive()
+
+-- fold disable
+require("trouble").fold_disable()
+
+-- fold enable
+require("trouble").fold_enable()
+
+-- fold more
+require("trouble").fold_more()
+
+-- Fold open
+require("trouble").fold_open()
+
+-- fold open all
+require("trouble").fold_open_all()
 
--- jump to the previous item, skipping the groups
-require("trouble").previous({skip_groups = true, jump = true});
+-- Fold open recursive
+require("trouble").fold_open_recursive()
 
--- jump to the first item, skipping the groups
-require("trouble").first({skip_groups = true, jump = true});
+-- fold reduce
+require("trouble").fold_reduce()
 
--- jump to the last item, skipping the groups
-require("trouble").last({skip_groups = true, jump = true});
+-- Fold toggle
+require("trouble").fold_toggle()
+
+-- fold toggle enable
+require("trouble").fold_toggle_enable()
+
+-- Fold toggle recursive
+require("trouble").fold_toggle_recursive()
+
+-- fold update
+require("trouble").fold_update()
+
+-- fold update all
+require("trouble").fold_update_all()
+
+-- help
+require("trouble").help()
+
+-- inspect
+require("trouble").inspect()
+
+-- jump
+require("trouble").jump()
+
+-- jump close
+require("trouble").jump_close()
+
+-- jump only
+require("trouble").jump_only()
+
+-- jump split
+require("trouble").jump_split()
+
+-- jump vsplit
+require("trouble").jump_vsplit()
+
+-- last
+require("trouble").last()
+
+-- next
+require("trouble").next()
+
+-- prev
+require("trouble").prev()
+
+-- preview
+require("trouble").preview()
+
+-- previous
+require("trouble").previous()
+
+-- refresh
+require("trouble").refresh()
+
+-- toggle preview
+require("trouble").toggle_preview()
+
+-- toggle refresh
+require("trouble").toggle_refresh()
 ```
 
+<!-- api:end -->
+
 ### Telescope
 
 You can easily open any search results in **Trouble**, by defining a custom action:
@@ -331,49 +462,49 @@ The table below shows all the highlight groups defined for Trouble.
 
 <!-- colors:start -->
 
-| Highlight Group | Default Group | Description |
-| --- | --- | --- |
-| **TroubleCount** | ***TabLineSel*** |  |
-| **TroubleDirectory** | ***Directory*** |  |
-| **TroubleFileName** | ***Directory*** |  |
-| **TroubleIconArray** | ***@punctuation.bracket*** |  |
-| **TroubleIconBoolean** | ***@boolean*** |  |
-| **TroubleIconClass** | ***@type*** |  |
-| **TroubleIconConstant** | ***@constant*** |  |
-| **TroubleIconConstructor** | ***@constructor*** |  |
-| **TroubleIconDirectory** | ***Special*** |  |
-| **TroubleIconEnum** | ***@lsp.type.enum*** |  |
-| **TroubleIconEnumMember** | ***@lsp.type.enumMember*** |  |
-| **TroubleIconEvent** | ***Special*** |  |
-| **TroubleIconField** | ***@field*** |  |
-| **TroubleIconFile** | ***Normal*** |  |
-| **TroubleIconFunction** | ***@function*** |  |
-| **TroubleIconInterface** | ***@lsp.type.interface*** |  |
-| **TroubleIconKey** | ***@lsp.type.keyword*** |  |
-| **TroubleIconMethod** | ***@method*** |  |
-| **TroubleIconModule** | ***@namespace*** |  |
-| **TroubleIconNamespace** | ***@namespace*** |  |
-| **TroubleIconNull** | ***@constant.builtin*** |  |
-| **TroubleIconNumber** | ***@number*** |  |
-| **TroubleIconObject** | ***@constant*** |  |
-| **TroubleIconOperator** | ***@operator*** |  |
-| **TroubleIconPackage** | ***@namespace*** |  |
-| **TroubleIconProperty** | ***@property*** |  |
-| **TroubleIconString** | ***@string*** |  |
-| **TroubleIconStruct** | ***@lsp.type.struct*** |  |
-| **TroubleIconTypeParameter** | ***@lsp.type.typeParameter*** |  |
-| **TroubleIconVariable** | ***@variable*** |  |
-| **TroubleIndent** | ***LineNr*** |  |
-| **TroubleIndentFoldClosed** | ***CursorLineNr*** |  |
-| **TroubleIndentFoldOpen** | ***TroubleIndent*** |  |
-| **TroubleIndentLast** | ***TroubleIndent*** |  |
-| **TroubleIndentMiddle** | ***TroubleIndent*** |  |
-| **TroubleIndentTop** | ***TroubleIndent*** |  |
-| **TroubleIndentWs** | ***TroubleIndent*** |  |
-| **TroubleNormal** | ***NormalFloat*** |  |
-| **TroublePos** | ***LineNr*** |  |
-| **TroublePreview** | ***Visual*** |  |
-| **TroubleSource** | ***Comment*** |  |
-| **TroubleText** | ***Normal*** |  |
+| Highlight Group              | Default Group                 | Description |
+| ---------------------------- | ----------------------------- | ----------- |
+| **TroubleCount**             | **_TabLineSel_**              |             |
+| **TroubleDirectory**         | **_Directory_**               |             |
+| **TroubleFileName**          | **_Directory_**               |             |
+| **TroubleIconArray**         | **_@punctuation.bracket_**    |             |
+| **TroubleIconBoolean**       | **_@boolean_**                |             |
+| **TroubleIconClass**         | **_@type_**                   |             |
+| **TroubleIconConstant**      | **_@constant_**               |             |
+| **TroubleIconConstructor**   | **_@constructor_**            |             |
+| **TroubleIconDirectory**     | **_Special_**                 |             |
+| **TroubleIconEnum**          | **_@lsp.type.enum_**          |             |
+| **TroubleIconEnumMember**    | **_@lsp.type.enumMember_**    |             |
+| **TroubleIconEvent**         | **_Special_**                 |             |
+| **TroubleIconField**         | **_@field_**                  |             |
+| **TroubleIconFile**          | **_Normal_**                  |             |
+| **TroubleIconFunction**      | **_@function_**               |             |
+| **TroubleIconInterface**     | **_@lsp.type.interface_**     |             |
+| **TroubleIconKey**           | **_@lsp.type.keyword_**       |             |
+| **TroubleIconMethod**        | **_@method_**                 |             |
+| **TroubleIconModule**        | **_@namespace_**              |             |
+| **TroubleIconNamespace**     | **_@namespace_**              |             |
+| **TroubleIconNull**          | **_@constant.builtin_**       |             |
+| **TroubleIconNumber**        | **_@number_**                 |             |
+| **TroubleIconObject**        | **_@constant_**               |             |
+| **TroubleIconOperator**      | **_@operator_**               |             |
+| **TroubleIconPackage**       | **_@namespace_**              |             |
+| **TroubleIconProperty**      | **_@property_**               |             |
+| **TroubleIconString**        | **_@string_**                 |             |
+| **TroubleIconStruct**        | **_@lsp.type.struct_**        |             |
+| **TroubleIconTypeParameter** | **_@lsp.type.typeParameter_** |             |
+| **TroubleIconVariable**      | **_@variable_**               |             |
+| **TroubleIndent**            | **_LineNr_**                  |             |
+| **TroubleIndentFoldClosed**  | **_CursorLineNr_**            |             |
+| **TroubleIndentFoldOpen**    | **_TroubleIndent_**           |             |
+| **TroubleIndentLast**        | **_TroubleIndent_**           |             |
+| **TroubleIndentMiddle**      | **_TroubleIndent_**           |             |
+| **TroubleIndentTop**         | **_TroubleIndent_**           |             |
+| **TroubleIndentWs**          | **_TroubleIndent_**           |             |
+| **TroubleNormal**            | **_NormalFloat_**             |             |
+| **TroublePos**               | **_LineNr_**                  |             |
+| **TroublePreview**           | **_Visual_**                  |             |
+| **TroubleSource**            | **_Comment_**                 |             |
+| **TroubleText**              | **_Normal_**                  |             |
 
 <!-- colors:end -->

lua/trouble/docs.lua

@@ -1,5 +1,6 @@
 local Config = require("trouble.config")
 local Docs = require("lazy.docs")
+local LazyUtil = require("lazy.util")
 
 local M = {}
 
@@ -14,6 +15,7 @@ function M.update()
       name = "Trouble",
     }),
     modes = M.modes(),
+    api = M.api(),
   })
 end
 
@@ -31,6 +33,47 @@ function M.modes()
   return { content = table.concat(lines, "\n") }
 end
 
+---@return ReadmeBlock
+function M.api()
+  local lines = vim.split(LazyUtil.read_file("lua/trouble/api.lua"), "\n")
+
+  local funcs = {}
+
+  ---@type string[]
+  local f = {}
+
+  for _, line in ipairs(lines) do
+    if line:match("^%-%-") then
+      f[#f + 1] = line
+    elseif line:match("^function") then
+      f[#f + 1] = line:gsub("^function M", [[require("trouble")]])
+      funcs[#funcs + 1] = table.concat(f, "\n")
+      f = {}
+    else
+      f = {}
+    end
+  end
+  local Actions = require("trouble.config.actions")
+  local names = vim.tbl_keys(Actions)
+  table.sort(names)
+
+  for _, k in ipairs(names) do
+    local desc = k:gsub("_", " ")
+    local action = Actions[k]
+    if type(Actions[k]) == "table" then
+      desc = action.desc or desc
+      action = action.action
+    end
+    if type(action) == "function" then
+      funcs[#funcs + 1] = ([[
+-- %s
+require("trouble").%s()]]):format(desc, k)
+    end
+  end
+  return { content = table.concat(funcs, "\n\n"), lang = "lua" }
+end
+
 M.update()
+-- M.api()
 
 return M