docs: docgen

2025-07-07 13:15:08 +00:00 · 2025-02-18 22:54:32 +01:00 · 2025-02-18 22:54:32 +01:00 · 3bfaffdd23
commit 3bfaffdd23
parent 1adfd29af3
8 changed files with 125 additions and 29 deletions
--- a/doc/snacks-debug.txt
+++ b/doc/snacks-debug.txt
@ -45,6 +45,20 @@ Whatthis does:
 ==============================================================================
 1. Types                                                  *snacks-debug-types*

+>lua
+    ---@class snacks.debug.cmd
+    ---@field cmd string|string[]
+    ---@field level? snacks.notifier.level
+    ---@field title? string
+    ---@field args? string[]
+    ---@field cwd? string
+    ---@field group? boolean
+    ---@field notify? boolean
+    ---@field footer? string
+    ---@field header? string
+    ---@field props? table<string, string>
+<
+
 >lua
    ---@alias snacks.debug.Trace {name: string, time: number, [number]:snacks.debug.Trace}
    ---@alias snacks.debug.Stat {name:string, time:number, count?:number, depth?:number}
@ -77,7 +91,7 @@ Show a notification with a pretty backtrace
 `Snacks.debug.cmd()`                                      *Snacks.debug.cmd()*

 >lua
-    ---@param opts {cmd: string|string[], args?: string[], cwd?: string}
+    ---@param opts snacks.debug.cmd
    Snacks.debug.cmd(opts)
 <

--- a/doc/snacks-image.txt
+++ b/doc/snacks-image.txt
@ -22,7 +22,7 @@ Table of Contents                             *snacks-image-table-of-contents*

 - Image viewer using the Kitty Graphics Protocol <https://sw.kovidgoyal.net/kitty/graphics-protocol/>.
 - open images in a wide range of formats:
-    `png`, `jpg`, `jpeg`, `gif`, `bmp`, `webp`, `tiff`, `heic`, `avif`, `mp4`, `mov`, `avi`, `mkv`, `webm`
+    `pdf`, `png`, `jpg`, `jpeg`, `gif`, `bmp`, `webp`, `tiff`, `heic`, `avif`, `mp4`, `mov`, `avi`, `mkv`, `webm`
 - Supports inline image rendering in:
    `markdown`, `html`, `norg`, `tsx`, `javascript`, `css`, `vue`, `svelte`, `scss`, `latex`, `typst`
 - LaTex math expressions in `markdown` and `latex` documents
@ -92,8 +92,25 @@ In case of issues, make sure to run `:checkhealth snacks`.
    --- Return the absolute path or url to the image.
    --- When `nil`, the path is resolved relative to the file.
    ---@field resolve? fun(file: string, src: string): string?
+    ---@field convert? snacks.image.convert.Config
    {
-      formats = { "png", "jpg", "jpeg", "gif", "bmp", "webp", "tiff", "heic", "avif", "mp4", "mov", "avi", "mkv", "webm" },
+      formats = {
+        "png",
+        "jpg",
+        "jpeg",
+        "gif",
+        "bmp",
+        "webp",
+        "tiff",
+        "heic",
+        "avif",
+        "mp4",
+        "mov",
+        "avi",
+        "mkv",
+        "webm",
+        "pdf",
+      },
      force = false, -- try displaying the image, even if the terminal does not support it
      doc = {
        -- enable image viewer for documents
@ -131,6 +148,21 @@ In case of issues, make sure to run `:checkhealth snacks`.
        placement = false,
      },
      env = {},
+      ---@class snacks.image.convert.Config
+      convert = {
+        notify = true, -- show a notification on error
+        ---@type snacks.image.args
+        mermaid = function()
+          local theme = vim.o.background == "light" and "neutral" or "dark"
+          return { "-i", "{src}", "-o", "{file}", "-b", "transparent", "-t", theme, "-s", "{scale}" }
+        end,
+        ---@type table<string,snacks.image.args>
+        magick = {
+          default = { "{src}[0]", "-scale", "1920x1080>" },
+          math = { "-density", 600, "{src}[0]", "-trim" },
+          pdf = { "-density", 300, "{src}[0]", "-background", "white", "-alpha", "remove", "-trim" },
+        },
+      },
    }
 <

--- a/doc/snacks-init.txt
+++ b/doc/snacks-init.txt
@ -42,10 +42,27 @@ Table of Contents                              *snacks-init-table-of-contents*
    ---@field words? snacks.words.Config
    ---@field zen? snacks.zen.Config
    ---@field styles? table<string, snacks.win.Config>
+    ---@field image? snacks.image.Config|{}
    {
      image = {
        -- define these here, so that we don't need to load the image module
-        formats = { "png", "jpg", "jpeg", "gif", "bmp", "webp", "tiff", "heic", "avif", "mp4", "mov", "avi", "mkv", "webm" },
+        formats = {
+          "png",
+          "jpg",
+          "jpeg",
+          "gif",
+          "bmp",
+          "webp",
+          "tiff",
+          "heic",
+          "avif",
+          "mp4",
+          "mov",
+          "avi",
+          "mkv",
+          "webm",
+          "pdf",
+        },
      },
    }
 <
--- a/doc/snacks-picker.txt
+++ b/doc/snacks-picker.txt
@ -347,6 +347,10 @@ below.
      },
      ---@class snacks.picker.previewers.Config
      previewers = {
+        diff = {
+          native = false, -- use native (terminal) or Neovim for previewing git diffs and commits
+          cmd = { "delta" }, -- example to show a diff with delta
+        },
        git = {
          native = false, -- use native (terminal) or Neovim for previewing git diffs and commits
          args = {}, -- additional arguments passed to the git command. Useful to set pager options usin `-c ...`
@ -793,23 +797,6 @@ TROUBLE                                       *snacks-picker-examples-trouble*
    ---@field notify? boolean
 <

->lua
-    ---@alias snacks.Picker.ref (fun():snacks.Picker?)|{value?: snacks.Picker}
-<
-
->lua
-    ---@class snacks.picker.Last
-    ---@field cursor number
-    ---@field topline number
-    ---@field opts? snacks.picker.Config
-    ---@field selected snacks.picker.Item[]
-    ---@field filter snacks.picker.Filter
-<
-
->lua
-    ---@alias snacks.picker.history.Record {pattern: string, search: string, live?: boolean}
-<
-
 >lua
    ---@alias snacks.picker.Extmark vim.api.keyset.set_extmark|{col:number, row?:number, field?:string}
    ---@alias snacks.picker.Text {[1]:string, [2]:string?, virtual?:boolean, field?:string}
@ -888,6 +875,23 @@ that shows a preview based on the item data.
    ---@field preview? snacks.win.Config|{} preview window config
 <

+>lua
+    ---@alias snacks.Picker.ref (fun():snacks.Picker?)|{value?: snacks.Picker}
+<
+
+>lua
+    ---@class snacks.picker.Last
+    ---@field cursor number
+    ---@field topline number
+    ---@field opts? snacks.picker.Config
+    ---@field selected snacks.picker.Item[]
+    ---@field filter snacks.picker.Filter
+<
+
+>lua
+    ---@alias snacks.picker.history.Record {pattern: string, search: string, live?: boolean}
+<
+

 ==============================================================================
 7. Module                                               *snacks-picker-module*
@ -1259,6 +1263,7 @@ GIT_BRANCHES                              *snacks-picker-sources-git_branches*
 <

 >lua
+    ---@type snacks.picker.git.Config
    {
      finder = "git_branches",
      format = "git_branch",
@ -1272,6 +1277,7 @@ GIT_BRANCHES                              *snacks-picker-sources-git_branches*
          },
        },
      },
+      ---@param picker snacks.Picker
      on_show = function(picker)
        for i, item in ipairs(picker:items()) do
          if item.current then
@ -1292,6 +1298,7 @@ GIT_DIFF                                      *snacks-picker-sources-git_diff*
 <

 >lua
+    ---@type snacks.picker.git.Config
    {
      finder = "git_diff",
      format = "file",
@ -1309,7 +1316,7 @@ GIT_FILES                                    *snacks-picker-sources-git_files*
 Find git files

 >lua
-    ---@class snacks.picker.git.files.Config: snacks.picker.Config
+    ---@class snacks.picker.git.files.Config: snacks.picker.git.Config
    ---@field untracked? boolean show untracked files
    ---@field submodules? boolean show submodule files
    {
@ -1331,8 +1338,7 @@ GIT_GREP                                      *snacks-picker-sources-git_grep*
 Grep in git files

 >lua
-    ---@class snacks.picker.git.grep.Config: snacks.picker.Config
-    ---@field args? string[] additional arguments to pass to `git grep`
+    ---@class snacks.picker.git.grep.Config: snacks.picker.git.Config
    ---@field untracked? boolean search in untracked files
    ---@field submodules? boolean search in submodule files
    ---@field need_search? boolean require a search pattern
@ -1358,15 +1364,17 @@ GIT_LOG                                        *snacks-picker-sources-git_log*
 Git log

 >lua
-    ---@class snacks.picker.git.log.Config: snacks.picker.Config
+    ---@class snacks.picker.git.log.Config: snacks.picker.git.Config
    ---@field follow? boolean track file history across renames
    ---@field current_file? boolean show current file log
    ---@field current_line? boolean show current line log
+    ---@field author? string filter commits by author
    {
      finder = "git_log",
      format = "git_log",
      preview = "git_show",
      confirm = "git_checkout",
+      sort = { fields = { "score:desc", "idx" } },
    }
 <

@ -1386,6 +1394,7 @@ GIT_LOG_FILE                              *snacks-picker-sources-git_log_file*
      current_file = true,
      follow = true,
      confirm = "git_checkout",
+      sort = { fields = { "score:desc", "idx" } },
    }
 <

@ -1405,6 +1414,7 @@ GIT_LOG_LINE                              *snacks-picker-sources-git_log_line*
      current_line = true,
      follow = true,
      confirm = "git_checkout",
+      sort = { fields = { "score:desc", "idx" } },
    }
 <

@ -1432,7 +1442,7 @@ GIT_STATUS                                  *snacks-picker-sources-git_status*
 <

 >lua
-    ---@class snacks.picker.git.status.Config: snacks.picker.Config
+    ---@class snacks.picker.git.status.Config: snacks.picker.git.Config
    ---@field ignored? boolean show ignored files
    {
      finder = "git_status",
@ -2302,7 +2312,7 @@ UNDO                                              *snacks-picker-sources-undo*
    {
      finder = "vim_undo",
      format = "undo",
-      preview = "preview",
+      preview = "diff",
      confirm = "item_action",
      win = {
        preview = { wo = { number = false, relativenumber = false, signcolumn = "no" } },
--- a/doc/snacks-util.txt
+++ b/doc/snacks-util.txt
@ -22,6 +22,7 @@ Table of Contents                              *snacks-util-table-of-contents*
  - Snacks.util.redraw_range() |snacks-util-module-snacks.util.redraw_range()|
  - Snacks.util.ref()                   |snacks-util-module-snacks.util.ref()|
  - Snacks.util.set_hl()             |snacks-util-module-snacks.util.set_hl()|
+  - Snacks.util.spinner()           |snacks-util-module-snacks.util.spinner()|
  - Snacks.util.throttle()         |snacks-util-module-snacks.util.throttle()|
  - Snacks.util.var()                   |snacks-util-module-snacks.util.var()|
  - Snacks.util.winhl()               |snacks-util-module-snacks.util.winhl()|
@ -211,6 +212,13 @@ Ensures the hl groups are always set, even after a colorscheme change.
 <


+`Snacks.util.spinner()`                                *Snacks.util.spinner()*
+
+>lua
+    Snacks.util.spinner()
+<
+
+
 `Snacks.util.throttle()`                              *Snacks.util.throttle()*

 >lua
--- a/doc/snacks.nvim.txt
+++ b/doc/snacks.nvim.txt
@ -1,4 +1,4 @@
-*snacks.nvim.txt*           For Neovim           Last change: 2025 February 18
+*snacks*           For Neovim           Last change: 2025 February 18

 ==============================================================================
 Table of Contents                              *snacks.nvim-table-of-contents*
--- a/docs/debug.md
+++ b/docs/debug.md
@ -29,6 +29,20 @@ What this does:

 ## 📚 Types

+```lua
+---@class snacks.debug.cmd
+---@field cmd string|string[]
+---@field level? snacks.notifier.level
+---@field title? string
+---@field args? string[]
+---@field cwd? string
+---@field group? boolean
+---@field notify? boolean
+---@field footer? string
+---@field header? string
+---@field props? table<string, string>
+```
+
 ```lua
 ---@alias snacks.debug.Trace {name: string, time: number, [number]:snacks.debug.Trace}
 ---@alias snacks.debug.Stat {name:string, time:number, count?:number, depth?:number}
@ -56,7 +70,7 @@ Snacks.debug.backtrace(msg, opts)
 ### `Snacks.debug.cmd()`

 ```lua
---@param opts {cmd: string|string[], args?: string[], cwd?: string, group?: boolean, notify?: boolean}
+---@param opts snacks.debug.cmd
 Snacks.debug.cmd(opts)
 ```

--- a/docs/image.md
+++ b/docs/image.md
@ -130,6 +130,7 @@ In case of issues, make sure to run `:checkhealth snacks`.
  env = {},
  ---@class snacks.image.convert.Config
  convert = {
+    notify = true, -- show a notification on error
    ---@type snacks.image.args
    mermaid = function()
      local theme = vim.o.background == "light" and "neutral" or "dark"