docs: more docs...

doc/snacks-git.txt

@@ -36,7 +36,7 @@ SNACKS.GIT.BLAME_LINE()            *snacks-git-module-snacks.git.blame_line()*
 Show git log for the current line.
 
 >lua
-    ---@param opts? snacks.terminal.Config | {count?: number}
+    ---@param opts? snacks.terminal.Opts | {count?: number}
     Snacks.git.blame_line(opts)
 <
 

doc/snacks-lazygit.txt

@@ -17,7 +17,7 @@ Table of Contents                           *snacks-lazygit-table-of-contents*
 1. Config                                              *snacks-lazygit-config*
 
 >lua
-    ---@class snacks.lazygit.Config: snacks.terminal.Config
+    ---@class snacks.lazygit.Config: snacks.terminal.Opts
     ---@field args? string[]
     ---@field theme? snacks.lazygit.Theme
     {

doc/snacks-notifier.txt

@@ -82,7 +82,6 @@ Notification options
     ---@field title? string
     ---@field icon? string
     ---@field timeout? number
-    ---@field once? boolean
     ---@field ft? string
     ---@field keep? fun(notif: snacks.notifier.Notif): boolean
     ---@field style? snacks.notifier.style

doc/snacks-notify.txt

@@ -15,7 +15,7 @@ Table of Contents                            *snacks-notify-table-of-contents*
 1. Types                                                 *snacks-notify-types*
 
 >lua
-    ---@alias snacks.notify.Opts {level?: number, title?: string, once?: boolean, ft?: string}
+    ---@alias snacks.notify.Opts snacks.notifier.Notif.opts|{once?: boolean}
 <
 
 

doc/snacks-quickfile.txt

@@ -4,6 +4,9 @@
 Table of Contents                         *snacks-quickfile-table-of-contents*
 
 1. Config                                            |snacks-quickfile-config|
+When doing `nvim somefile.txt`, it will render the file as quickly as possible,
+before loading your plugins.
+
 
 ==============================================================================
 1. Config                                            *snacks-quickfile-config*

doc/snacks-rename.txt

@@ -58,6 +58,8 @@ LSP-integrated file renaming with support for plugins like neo-tree.nvim
 
 SNACKS.RENAME.ON_RENAME_FILE()*snacks-rename-module-snacks.rename.on_rename_file()*
 
+Lets LSP clients know that a file has been renamed
+
 >lua
     ---@param from string
     ---@param to string

doc/snacks-terminal.txt

@@ -6,21 +6,27 @@ Table of Contents                          *snacks-terminal-table-of-contents*
 1. Config                                             |snacks-terminal-config|
 2. Styles                                             |snacks-terminal-styles|
   - terminal                                 |snacks-terminal-styles-terminal|
-3. Module                                             |snacks-terminal-module|
+3. Types                                               |snacks-terminal-types|
+4. Module                                             |snacks-terminal-module|
   - Snacks.terminal()               |snacks-terminal-module-snacks.terminal()|
   - Snacks.terminal.open()     |snacks-terminal-module-snacks.terminal.open()|
   - Snacks.terminal.toggle() |snacks-terminal-module-snacks.terminal.toggle()|
+Create and toggle terminal windows.
+
+Based on the provided options, some defaults will be set:
+
+- if no `cmd` is provided, the window will be opened in a bottom split
+- if `cmd` is provided, the window will be opened in a floating window
+- for splits, a `winbar` will be added with the terminal title
+
 
 ==============================================================================
 1. Config                                             *snacks-terminal-config*
 
 >lua
     ---@class snacks.terminal.Config
-    ---@field cwd? string
-    ---@field env? table<string, string>
     ---@field win? snacks.win.Config
-    ---@field interactive? boolean
+    ---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Opts) Use this to use a different terminal implementation
-    ---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Config) Use this to use a different terminal implementation
     {
       win = { style = "terminal" },
     }
@@ -71,12 +77,23 @@ TERMINAL                                     *snacks-terminal-styles-terminal*
 
 
 ==============================================================================
-3. Module                                             *snacks-terminal-module*
+3. Types                                               *snacks-terminal-types*
+
+>lua
+    ---@class snacks.terminal.Opts: snacks.terminal.Config
+    ---@field cwd? string
+    ---@field env? table<string, string>
+    ---@field interactive? boolean
+<
+
+
+==============================================================================
+4. Module                                             *snacks-terminal-module*
 
 >lua
     ---@class snacks.terminal: snacks.win
     ---@field cmd? string | string[]
-    ---@field opts snacks.terminal.Config
+    ---@field opts snacks.terminal.Opts
     Snacks.terminal = {}
 <
 
@@ -84,25 +101,30 @@ TERMINAL                                     *snacks-terminal-styles-terminal*
 SNACKS.TERMINAL()                   *snacks-terminal-module-snacks.terminal()*
 
 >lua
-    ---@type fun(cmd?: string|string[], opts?: snacks.terminal.Config): snacks.terminal
+    ---@type fun(cmd?: string|string[], opts?: snacks.terminal.Opts): snacks.terminal
     Snacks.terminal()
 <
 
 
 SNACKS.TERMINAL.OPEN()         *snacks-terminal-module-snacks.terminal.open()*
 
+Open a new terminal window.
+
 >lua
     ---@param cmd? string | string[]
-    ---@param opts? snacks.terminal.Config
+    ---@param opts? snacks.terminal.Opts
     Snacks.terminal.open(cmd, opts)
 <
 
 
 SNACKS.TERMINAL.TOGGLE()     *snacks-terminal-module-snacks.terminal.toggle()*
 
+Toggle a terminal window. The terminal id is based on the `cmd`, `cwd`, `env`
+and `vim.v.count1` options.
+
 >lua
     ---@param cmd? string | string[]
-    ---@param opts? snacks.terminal.Config
+    ---@param opts? snacks.terminal.Opts
     Snacks.terminal.toggle(cmd, opts)
 <
 

doc/snacks-toggle.txt

@@ -17,6 +17,8 @@ Table of Contents                            *snacks-toggle-table-of-contents*
   - toggle:map()                           |snacks-toggle-module-toggle:map()|
   - toggle:set()                           |snacks-toggle-module-toggle:set()|
   - toggle:toggle()                     |snacks-toggle-module-toggle:toggle()|
+Toggle keymaps integrated with which-key icons / colors
+
 
 ==============================================================================
 1. Config                                               *snacks-toggle-config*

doc/snacks-win.txt

@@ -3,16 +3,16 @@
 ==============================================================================
 Table of Contents                               *snacks-win-table-of-contents*
 
-1. Config                                                  |snacks-win-config|
+1. Usage                                                    |snacks-win-usage|
-2. Styles                                                  |snacks-win-styles|
+2. Config                                                  |snacks-win-config|
+3. Styles                                                  |snacks-win-styles|
   - float                                            |snacks-win-styles-float|
   - minimal                                        |snacks-win-styles-minimal|
   - split                                            |snacks-win-styles-split|
-3. Types                                                    |snacks-win-types|
+4. Types                                                    |snacks-win-types|
-4. Module                                                  |snacks-win-module|
+5. Module                                                  |snacks-win-module|
   - Snacks.win()                              |snacks-win-module-snacks.win()|
   - Snacks.win.new()                      |snacks-win-module-snacks.win.new()|
-  - Snacks.win.resolve()              |snacks-win-module-snacks.win.resolve()|
   - win:add_padding()                    |snacks-win-module-win:add_padding()|
   - win:buf_valid()                        |snacks-win-module-win:buf_valid()|
   - win:close()                                |snacks-win-module-win:close()|
@@ -24,9 +24,30 @@ Table of Contents                               *snacks-win-table-of-contents*
   - win:update()                              |snacks-win-module-win:update()|
   - win:valid()                                |snacks-win-module-win:valid()|
   - win:win_valid()                        |snacks-win-module-win:win_valid()|
+Easily create and manage floating windows or splits
+
 
 ==============================================================================
-1. Config                                                  *snacks-win-config*
+1. Usage                                                    *snacks-win-usage*
+
+>lua
+    Snacks.win({
+      file = vim.api.nvim_get_runtime_file("doc/news.txt", false)[1],
+      width = 0.6,
+      height = 0.6,
+      wo = {
+        spell = false,
+        wrap = false,
+        signcolumn = "yes",
+        statuscolumn = " ",
+        conceallevel = 3,
+      },
+    })
+<
+
+
+==============================================================================
+2. Config                                                  *snacks-win-config*
 
 >lua
     ---@class snacks.win.Config: vim.api.keyset.win_config
@@ -60,7 +81,7 @@ Table of Contents                               *snacks-win-table-of-contents*
 
 
 ==============================================================================
-2. Styles                                                  *snacks-win-styles*
+3. Styles                                                  *snacks-win-styles*
 
 
 FLOAT                                                *snacks-win-styles-float*
@@ -113,7 +134,7 @@ SPLIT                                                *snacks-win-styles-split*
 
 
 ==============================================================================
-3. Types                                                    *snacks-win-types*
+4. Types                                                    *snacks-win-types*
 
 >lua
     ---@class snacks.win.Keys: vim.api.keyset.keymap
@@ -124,7 +145,7 @@ SPLIT                                                *snacks-win-styles-split*
 
 
 ==============================================================================
-4. Module                                                  *snacks-win-module*
+5. Module                                                  *snacks-win-module*
 
 >lua
     ---@class snacks.win
@@ -155,15 +176,6 @@ SNACKS.WIN.NEW()                          *snacks-win-module-snacks.win.new()*
 <
 
 
-SNACKS.WIN.RESOLVE()                  *snacks-win-module-snacks.win.resolve()*
-
->lua
-    ---@param ... snacks.win.Config|string
-    ---@return snacks.win.Config
-    Snacks.win.resolve(...)
-<
-
-
 WIN:ADD_PADDING()                        *snacks-win-module-win:add_padding()*
 
 >lua

doc/snacks-words.txt

@@ -7,6 +7,8 @@ Table of Contents                             *snacks-words-table-of-contents*
 2. Module                                                |snacks-words-module|
   - Snacks.words.is_enabled()  |snacks-words-module-snacks.words.is_enabled()|
   - Snacks.words.jump()              |snacks-words-module-snacks.words.jump()|
+Auto-show LSP references and quickly navigate between them
+
 
 ==============================================================================
 1. Config                                                *snacks-words-config*

docs/git.md

@@ -24,7 +24,7 @@
 Show git log for the current line.
 
 ```lua
----@param opts? snacks.terminal.Config | {count?: number}
+---@param opts? snacks.terminal.Opts | {count?: number}
 Snacks.git.blame_line(opts)
 ```
 

docs/lazygit.md

@@ -5,7 +5,7 @@
 ## ⚙️ Config
 
 ```lua
----@class snacks.lazygit.Config: snacks.terminal.Config
+---@class snacks.lazygit.Config: snacks.terminal.Opts
 ---@field args? string[]
 ---@field theme? snacks.lazygit.Theme
 {

docs/notifier.md

@@ -65,7 +65,6 @@ Notification options
 ---@field title? string
 ---@field icon? string
 ---@field timeout? number
----@field once? boolean
 ---@field ft? string
 ---@field keep? fun(notif: snacks.notifier.Notif): boolean
 ---@field style? snacks.notifier.style

docs/notify.md

@@ -5,7 +5,7 @@
 ## 📚 Types
 
 ```lua
----@alias snacks.notify.Opts {level?: number, title?: string, once?: boolean, ft?: string}
+---@alias snacks.notify.Opts snacks.notifier.Notif.opts|{once?: boolean}
 ```
 
 ## 📦 Module

docs/quickfile.md

@@ -1,5 +1,8 @@
 # 🍿 quickfile
 
+When doing `nvim somefile.txt`, it will render the file as quickly as possible,
+before loading your plugins.
+
 <!-- docgen -->
 
 ## ⚙️ Config

docs/rename.md

@@ -41,6 +41,8 @@ vim.api.nvim_create_autocmd("User", {
 
 ### `Snacks.rename.on_rename_file()`
 
+Lets LSP clients know that a file has been renamed
+
 ```lua
 ---@param from string
 ---@param to string

docs/terminal.md

@@ -1,16 +1,21 @@
 # 🍿 terminal
 
+Create and toggle terminal windows.
+
+Based on the provided options, some defaults will be set:
+
+- if no `cmd` is provided, the window will be opened in a bottom split
+- if `cmd` is provided, the window will be opened in a floating window
+- for splits, a `winbar` will be added with the terminal title
+
 <!-- docgen -->
 
 ## ⚙️ Config
 
 ```lua
 ---@class snacks.terminal.Config
----@field cwd? string
----@field env? table<string, string>
 ---@field win? snacks.win.Config
----@field interactive? boolean
+---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Opts) Use this to use a different terminal implementation
----@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Config) Use this to use a different terminal implementation
 {
   win = { style = "terminal" },
 }
@@ -56,34 +61,48 @@
 }
 ```
 
+## 📚 Types
+
+```lua
+---@class snacks.terminal.Opts: snacks.terminal.Config
+---@field cwd? string
+---@field env? table<string, string>
+---@field interactive? boolean
+```
+
 ## 📦 Module
 
 ```lua
 ---@class snacks.terminal: snacks.win
 ---@field cmd? string | string[]
----@field opts snacks.terminal.Config
+---@field opts snacks.terminal.Opts
 Snacks.terminal = {}
 ```
 
 ### `Snacks.terminal()`
 
 ```lua
----@type fun(cmd?: string|string[], opts?: snacks.terminal.Config): snacks.terminal
+---@type fun(cmd?: string|string[], opts?: snacks.terminal.Opts): snacks.terminal
 Snacks.terminal()
 ```
 
 ### `Snacks.terminal.open()`
 
+Open a new terminal window.
+
 ```lua
 ---@param cmd? string | string[]
----@param opts? snacks.terminal.Config
+---@param opts? snacks.terminal.Opts
 Snacks.terminal.open(cmd, opts)
 ```
 
 ### `Snacks.terminal.toggle()`
 
+Toggle a terminal window.
+The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
+
 ```lua
 ---@param cmd? string | string[]
----@param opts? snacks.terminal.Config
+---@param opts? snacks.terminal.Opts
 Snacks.terminal.toggle(cmd, opts)
 ```

docs/toggle.md

@@ -1,5 +1,7 @@
 # 🍿 toggle
 
+Toggle keymaps integrated with which-key icons / colors
+
 <!-- docgen -->
 
 ## ⚙️ Config

docs/win.md

@@ -1,5 +1,24 @@
 # 🍿 win
 
+Easily create and manage floating windows or splits
+
+## 🚀 Usage
+
+```lua
+Snacks.win({
+  file = vim.api.nvim_get_runtime_file("doc/news.txt", false)[1],
+  width = 0.6,
+  height = 0.6,
+  wo = {
+    spell = false,
+    wrap = false,
+    signcolumn = "yes",
+    statuscolumn = " ",
+    conceallevel = 3,
+  },
+})
+```
+
 <!-- docgen -->
 
 ## ⚙️ Config
@@ -119,14 +138,6 @@ Snacks.win()
 Snacks.win.new(opts)
 ```
 
-### `Snacks.win.resolve()`
-
-```lua
----@param ... snacks.win.Config|string
----@return snacks.win.Config
-Snacks.win.resolve(...)
-```
-
 ### `win:add_padding()`
 
 ```lua

docs/words.md

@@ -1,5 +1,7 @@
 # 🍿 words
 
+Auto-show LSP references and quickly navigate between them
+
 <!-- docgen -->
 
 ## ⚙️ Config

lua/snacks/git.lua

@@ -23,7 +23,7 @@ function M.get_root(path)
 end
 
 --- Show git log for the current line.
----@param opts? snacks.terminal.Config | {count?: number}
+---@param opts? snacks.terminal.Opts | {count?: number}
 function M.blame_line(opts)
   opts = vim.tbl_deep_extend("force", {
     count = 5,

lua/snacks/lazygit.lua

@@ -20,7 +20,7 @@ local M = setmetatable({}, {
 ---@field selectedLineBgColor snacks.lazygit.Color
 ---@field unstagedChangesColor snacks.lazygit.Color
 
----@class snacks.lazygit.Config: snacks.terminal.Config
+---@class snacks.lazygit.Config: snacks.terminal.Opts
 ---@field args? string[]
 ---@field theme? snacks.lazygit.Theme
 local defaults = {

lua/snacks/notifier.lua

@@ -23,7 +23,6 @@ local M = setmetatable({}, {
 ---@field title? string
 ---@field icon? string
 ---@field timeout? number
----@field once? boolean
 ---@field ft? string
 ---@field keep? fun(notif: snacks.notifier.Notif): boolean
 ---@field style? snacks.notifier.style
@@ -325,6 +324,7 @@ function N:render(notif)
       },
     })
   notif.win = win
+  ---@diagnostic disable-next-line: invisible
   local buf = win:open_buf()
   vim.api.nvim_buf_clear_namespace(buf, N.ns, 0, -1)
   local render = self:get_render(notif.style)
@@ -430,6 +430,7 @@ function N:layout()
       if not notif.win or notif.dirty or not notif.win:buf_valid() then
         notif.dirty = false
         self:render(notif)
+        ---@diagnostic disable-next-line: assign-type-mismatch
         notif.layout = notif.win:size()
       end
       notif.layout.top = find(notif.layout.height, notif.layout.top)

lua/snacks/notify.lua

@@ -7,7 +7,7 @@ local M = setmetatable({}, {
   end,
 })
 
----@alias snacks.notify.Opts {level?: number, title?: string, once?: boolean, ft?: string}
+---@alias snacks.notify.Opts snacks.notifier.Notif.opts|{once?: boolean}
 
 ---@param msg string|string[]
 ---@param opts? snacks.notify.Opts
@@ -17,44 +17,26 @@ function M.notify(msg, opts)
   notify = vim.in_fast_event() and vim.schedule_wrap(notify) or notify
   msg = type(msg) == "table" and table.concat(msg, "\n") or msg --[[@as string]]
   msg = vim.trim(msg)
-  notify(msg, opts.level, {
+  opts.title = opts.title or "Snacks"
-    title = opts.title or "Snacks",
+  return notify(msg, opts.level, opts)
-    ft = opts.ft,
-    -- used by nvim-notify
-    on_open = function(win)
-      vim.wo[win].conceallevel = 3
-      vim.wo[win].concealcursor = "n"
-      vim.wo[win].spell = false
-      local buf = vim.api.nvim_win_get_buf(win)
-      local ft = opts.ft or "markdown"
-      local lang = ft and vim.treesitter.language.get_lang(ft)
-      if lang and not vim.b[buf].ts_highlight and not pcall(vim.treesitter.start, buf, lang) then
-        lang = nil
-      end
-      if ft and not lang then
-        vim.bo[buf].filetype = ft
-        vim.bo[buf].syntax = ft
-      end
-    end,
-  })
 end
 
 ---@param msg string|string[]
 ---@param opts? snacks.notify.Opts
 function M.warn(msg, opts)
-  M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.WARN }, opts or {}))
+  return M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.WARN }, opts or {}))
 end
 
 ---@param msg string|string[]
 ---@param opts? snacks.notify.Opts
 function M.info(msg, opts)
-  M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.INFO }, opts or {}))
+  return M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.INFO }, opts or {}))
 end
 
 ---@param msg string|string[]
 ---@param opts? snacks.notify.Opts
 function M.error(msg, opts)
-  M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.ERROR }, opts or {}))
+  return M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.ERROR }, opts or {}))
 end
 
 return M

lua/snacks/rename.lua

@@ -41,6 +41,7 @@ function M.rename_file()
   end)
 end
 
+--- Lets LSP clients know that a file has been renamed
 ---@param from string
 ---@param to string
 ---@param rename? fun()

lua/snacks/terminal.lua

@@ -1,7 +1,7 @@
 ---@class snacks.terminal: snacks.win
 ---@field cmd? string | string[]
----@field opts snacks.terminal.Config
+---@field opts snacks.terminal.Opts
----@overload fun(cmd?: string|string[], opts?: snacks.terminal.Config): snacks.terminal
+---@overload fun(cmd?: string|string[], opts?: snacks.terminal.Opts): snacks.terminal
 local M = setmetatable({}, {
   __call = function(t, ...)
     return t.toggle(...)
@@ -9,15 +9,17 @@ local M = setmetatable({}, {
 })
 
 ---@class snacks.terminal.Config
----@field cwd? string
----@field env? table<string, string>
 ---@field win? snacks.win.Config
----@field interactive? boolean
+---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Opts) Use this to use a different terminal implementation
----@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Config) Use this to use a different terminal implementation
 local defaults = {
   win = { style = "terminal" },
 }
 
+---@class snacks.terminal.Opts: snacks.terminal.Config
+---@field cwd? string
+---@field env? table<string, string>
+---@field interactive? boolean
+
 Snacks.config.style("terminal", {
   bo = {
     filetype = "snacks_terminal",
@@ -55,12 +57,17 @@ Snacks.config.style("terminal", {
 ---@type table<string, snacks.win>
 local terminals = {}
 
+--- Open a new terminal window.
 ---@param cmd? string | string[]
----@param opts? snacks.terminal.Config
+---@param opts? snacks.terminal.Opts
 function M.open(cmd, opts)
   local id = vim.v.count1
-  ---@type snacks.terminal.Config
+  opts = Snacks.config.get(
-  opts = Snacks.config.get("terminal", defaults, { win = { position = cmd and "float" or "bottom" } }, opts)
+    "terminal",
+    defaults --[[@as snacks.terminal.Opts]],
+    { win = { position = cmd and "float" or "bottom" } },
+    opts
+  )
   opts.win = Snacks.win.resolve("terminal", opts.win)
   opts.win.wo.winbar = opts.win.wo.winbar or (opts.win.position == "float" and "" or (id .. ": %{b:term_title}"))
 
@@ -110,8 +117,10 @@ function M.open(cmd, opts)
   return terminal
 end
 
+--- Toggle a terminal window.
+--- The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
 ---@param cmd? string | string[]
----@param opts? snacks.terminal.Config
+---@param opts? snacks.terminal.Opts
 function M.toggle(cmd, opts)
   opts = opts or {}
 

lua/snacks/win.lua

@@ -117,10 +117,11 @@ local win_opts = {
   "zindex",
 }
 
-vim.api.nvim_set_hl(0, "SnackFloatBackdrop", { bg = "#000000", default = true })
+vim.api.nvim_set_hl(0, "SnacksWinBackdrop", { bg = "#000000", default = true })
 
 local id = 0
 
+---@private
 ---@param ... snacks.win.Config|string
 ---@return snacks.win.Config
 function M.resolve(...)
@@ -393,12 +394,12 @@ function M:drop()
       focusable = false,
       zindex = self.opts.zindex - 1,
       wo = {
-        winhighlight = "Normal:SnackFloatBackdrop",
+        winhighlight = "Normal:SnacksWinBackdrop",
         winblend = self.opts.backdrop,
       },
       bo = {
         buftype = "nofile",
-        filetype = "snack_float_backdrop",
+        filetype = "snacks_win_backdrop",
       },
     })
     vim.api.nvim_create_autocmd("WinClosed", {