docs: moar docs

doc/snacks-lazygit.txt

@@ -21,19 +21,22 @@ Table of Contents                           *snacks-lazygit-table-of-contents*
     ---@field args? string[]
     ---@field theme? snacks.lazygit.Theme
     {
+      -- automatically configure lazygit to use the current colorscheme
+      -- and integrate edit with the current neovim instance
       configure = true,
       theme_path = vim.fs.normalize(vim.fn.stdpath("cache") .. "/lazygit-theme.yml"),
+      -- Theme for lazygit
       theme = {
-        [241] = { fg = "Special" },
-        activeBorderColor = { fg = "MatchParen", bold = true },
-        cherryPickedCommitBgColor = { fg = "Identifier" },
-        cherryPickedCommitFgColor = { fg = "Function" },
-        defaultFgColor = { fg = "Normal" },
-        inactiveBorderColor = { fg = "FloatBorder" },
-        optionsTextColor = { fg = "Function" },
+        [241]                      = { fg = "Special" },
+        activeBorderColor          = { fg = "MatchParen", bold = true },
+        cherryPickedCommitBgColor  = { fg = "Identifier" },
+        cherryPickedCommitFgColor  = { fg = "Function" },
+        defaultFgColor             = { fg = "Normal" },
+        inactiveBorderColor        = { fg = "FloatBorder" },
+        optionsTextColor           = { fg = "Function" },
         searchingActiveBorderColor = { fg = "MatchParen", bold = true },
-        selectedLineBgColor = { bg = "Visual" }, -- set to `default` to have no background colour
-        unstagedChangesColor = { fg = "DiagnosticError" },
+        selectedLineBgColor        = { bg = "Visual" }, -- set to `default` to have no background colour
+        unstagedChangesColor       = { fg = "DiagnosticError" },
       },
       win = {
         style = "lazygit",

doc/snacks-notifier.txt

@@ -27,7 +27,7 @@ Table of Contents                          *snacks-notifier-table-of-contents*
     ---@class snacks.notifier.Config
     ---@field keep? fun(notif: snacks.notifier.Notif): boolean
     {
-      timeout = 3000,
+      timeout = 3000, -- default timeout in ms
       width = { min = 40, max = 0.4 },
       height = { min = 1, max = 0.6 },
       padding = true, -- add 1 cell of left/right padding to the notification window

doc/snacks-statuscolumn.txt

@@ -11,13 +11,14 @@ Table of Contents                      *snacks-statuscolumn-table-of-contents*
 >lua
     ---@class snacks.statuscolumn.Config
     {
-      left = { "mark", "sign" },
-      right = { "fold", "git" },
+      left = { "mark", "sign" }, -- priority of signs on the left (high to low)
+      right = { "fold", "git" }, -- priority of signs on the right (high to low)
       folds = {
         open = false, -- show open fold icons
         git_hl = false, -- use Git Signs hl for fold icons
       },
       git = {
+        -- patterns to match Git signs
         patterns = { "GitSign", "MiniDiffSign" },
       },
       refresh = 50, -- refresh at most every 50ms

doc/snacks-toggle.txt

@@ -26,13 +26,15 @@ Table of Contents                            *snacks-toggle-table-of-contents*
     ---@field icon? string|{ enabled: string, disabled: string }
     ---@field color? string|{ enabled: string, disabled: string }
     {
-      map = vim.keymap.set,
-      which_key = true,
-      notify = true,
+      map = vim.keymap.set, -- keymap.set function to use
+      which_key = true, -- integrate with which-key to show enabled/disabled icons and colors
+      notify = true, -- show a notification when toggling
+      -- icons for enabled/disabled states
       icon = {
         enabled = " ",
         disabled = " ",
       },
+      -- colors for enabled/disabled states
       color = {
         enabled = "green",
         disabled = "yellow",

doc/snacks-win.txt

@@ -30,20 +30,19 @@ Table of Contents                               *snacks-win-table-of-contents*
 
 >lua
     ---@class snacks.win.Config: vim.api.keyset.win_config
-    ---@field style? string merges with config from `Snacks.config.views[view]`
+    ---@field style? string merges with config from `Snacks.config.styles[style]`
     ---@field show? boolean Show the window immediately (default: true)
-    ---@field minimal? boolean
+    ---@field minimal? boolean Disable a bunch of options to make the window minimal (default: true)
     ---@field position? "float"|"bottom"|"top"|"left"|"right"
-    ---@field buf? number
-    ---@field file? string
-    ---@field enter? boolean
-    ---@field backdrop? number|false
-    ---@field win? vim.api.keyset.win_config
-    ---@field wo? vim.wo
-    ---@field bo? vim.bo
-    ---@field keys? table<string, false|string|fun(self: snacks.win)|snacks.win.Keys>
-    ---@field on_buf? fun(self: snacks.win)
-    ---@field on_win? fun(self: snacks.win)
+    ---@field buf? number If set, use this buffer instead of creating a new one
+    ---@field file? string If set, use this file instead of creating a new buffer
+    ---@field enter? boolean Enter the window after opening (default: false)
+    ---@field backdrop? number|false Opacity of the backdrop (default: 60)
+    ---@field wo? vim.wo window options
+    ---@field bo? vim.bo buffer options
+    ---@field keys? table<string, false|string|fun(self: snacks.win)|snacks.win.Keys> Key mappings
+    ---@field on_buf? fun(self: snacks.win) Callback after opening the buffer
+    ---@field on_win? fun(self: snacks.win) Callback after opening the window
     {
       show = true,
       relative = "editor",

doc/snacks-words.txt

@@ -14,8 +14,8 @@ Table of Contents                             *snacks-words-table-of-contents*
 >lua
     ---@class snacks.words.Config
     {
-      enabled = true,
-      debounce = 200,
+      enabled = true, -- enable/disable the plugin
+      debounce = 200, -- time in ms to wait before updating
     }
 <
 

docs/lazygit.md

@@ -9,19 +9,22 @@
 ---@field args? string[]
 ---@field theme? snacks.lazygit.Theme
 {
+  -- automatically configure lazygit to use the current colorscheme
+  -- and integrate edit with the current neovim instance
   configure = true,
   theme_path = vim.fs.normalize(vim.fn.stdpath("cache") .. "/lazygit-theme.yml"),
+  -- Theme for lazygit
   theme = {
-    [241] = { fg = "Special" },
-    activeBorderColor = { fg = "MatchParen", bold = true },
-    cherryPickedCommitBgColor = { fg = "Identifier" },
-    cherryPickedCommitFgColor = { fg = "Function" },
-    defaultFgColor = { fg = "Normal" },
-    inactiveBorderColor = { fg = "FloatBorder" },
-    optionsTextColor = { fg = "Function" },
+    [241]                      = { fg = "Special" },
+    activeBorderColor          = { fg = "MatchParen", bold = true },
+    cherryPickedCommitBgColor  = { fg = "Identifier" },
+    cherryPickedCommitFgColor  = { fg = "Function" },
+    defaultFgColor             = { fg = "Normal" },
+    inactiveBorderColor        = { fg = "FloatBorder" },
+    optionsTextColor           = { fg = "Function" },
     searchingActiveBorderColor = { fg = "MatchParen", bold = true },
-    selectedLineBgColor = { bg = "Visual" }, -- set to `default` to have no background colour
-    unstagedChangesColor = { fg = "DiagnosticError" },
+    selectedLineBgColor        = { bg = "Visual" }, -- set to `default` to have no background colour
+    unstagedChangesColor       = { fg = "DiagnosticError" },
   },
   win = {
     style = "lazygit",

docs/notifier.md

@@ -8,7 +8,7 @@
 ---@class snacks.notifier.Config
 ---@field keep? fun(notif: snacks.notifier.Notif): boolean
 {
-  timeout = 3000,
+  timeout = 3000, -- default timeout in ms
   width = { min = 40, max = 0.4 },
   height = { min = 1, max = 0.6 },
   padding = true, -- add 1 cell of left/right padding to the notification window

docs/statuscolumn.md

@@ -7,13 +7,14 @@
 ```lua
 ---@class snacks.statuscolumn.Config
 {
-  left = { "mark", "sign" },
-  right = { "fold", "git" },
+  left = { "mark", "sign" }, -- priority of signs on the left (high to low)
+  right = { "fold", "git" }, -- priority of signs on the right (high to low)
   folds = {
     open = false, -- show open fold icons
     git_hl = false, -- use Git Signs hl for fold icons
   },
   git = {
+    -- patterns to match Git signs
     patterns = { "GitSign", "MiniDiffSign" },
   },
   refresh = 50, -- refresh at most every 50ms

docs/toggle.md

@@ -9,13 +9,15 @@
 ---@field icon? string|{ enabled: string, disabled: string }
 ---@field color? string|{ enabled: string, disabled: string }
 {
-  map = vim.keymap.set,
-  which_key = true,
-  notify = true,
+  map = vim.keymap.set, -- keymap.set function to use
+  which_key = true, -- integrate with which-key to show enabled/disabled icons and colors
+  notify = true, -- show a notification when toggling
+  -- icons for enabled/disabled states
   icon = {
     enabled = " ",
     disabled = " ",
   },
+  -- colors for enabled/disabled states
   color = {
     enabled = "green",
     disabled = "yellow",

docs/win.md

@@ -6,20 +6,19 @@
 
 ```lua
 ---@class snacks.win.Config: vim.api.keyset.win_config
----@field style? string merges with config from `Snacks.config.views[view]`
+---@field style? string merges with config from `Snacks.config.styles[style]`
 ---@field show? boolean Show the window immediately (default: true)
----@field minimal? boolean
+---@field minimal? boolean Disable a bunch of options to make the window minimal (default: true)
 ---@field position? "float"|"bottom"|"top"|"left"|"right"
----@field buf? number
----@field file? string
----@field enter? boolean
----@field backdrop? number|false
----@field win? vim.api.keyset.win_config
----@field wo? vim.wo
----@field bo? vim.bo
----@field keys? table<string, false|string|fun(self: snacks.win)|snacks.win.Keys>
----@field on_buf? fun(self: snacks.win)
----@field on_win? fun(self: snacks.win)
+---@field buf? number If set, use this buffer instead of creating a new one
+---@field file? string If set, use this file instead of creating a new buffer
+---@field enter? boolean Enter the window after opening (default: false)
+---@field backdrop? number|false Opacity of the backdrop (default: 60)
+---@field wo? vim.wo window options
+---@field bo? vim.bo buffer options
+---@field keys? table<string, false|string|fun(self: snacks.win)|snacks.win.Keys> Key mappings
+---@field on_buf? fun(self: snacks.win) Callback after opening the buffer
+---@field on_win? fun(self: snacks.win) Callback after opening the window
 {
   show = true,
   relative = "editor",

docs/words.md

@@ -7,8 +7,8 @@
 ```lua
 ---@class snacks.words.Config
 {
-  enabled = true,
-  debounce = 200,
+  enabled = true, -- enable/disable the plugin
+  debounce = 200, -- time in ms to wait before updating
 }
 ```
 

lua/snacks/lazygit.lua

@@ -24,19 +24,23 @@ local M = setmetatable({}, {
 ---@field args? string[]
 ---@field theme? snacks.lazygit.Theme
 local defaults = {
+  -- automatically configure lazygit to use the current colorscheme
+  -- and integrate edit with the current neovim instance
   configure = true,
   theme_path = vim.fs.normalize(vim.fn.stdpath("cache") .. "/lazygit-theme.yml"),
+  -- Theme for lazygit
+  -- stylua: ignore
   theme = {
-    [241] = { fg = "Special" },
-    activeBorderColor = { fg = "MatchParen", bold = true },
-    cherryPickedCommitBgColor = { fg = "Identifier" },
-    cherryPickedCommitFgColor = { fg = "Function" },
-    defaultFgColor = { fg = "Normal" },
-    inactiveBorderColor = { fg = "FloatBorder" },
-    optionsTextColor = { fg = "Function" },
+    [241]                      = { fg = "Special" },
+    activeBorderColor          = { fg = "MatchParen", bold = true },
+    cherryPickedCommitBgColor  = { fg = "Identifier" },
+    cherryPickedCommitFgColor  = { fg = "Function" },
+    defaultFgColor             = { fg = "Normal" },
+    inactiveBorderColor        = { fg = "FloatBorder" },
+    optionsTextColor           = { fg = "Function" },
     searchingActiveBorderColor = { fg = "MatchParen", bold = true },
-    selectedLineBgColor = { bg = "Visual" }, -- set to `default` to have no background colour
-    unstagedChangesColor = { fg = "DiagnosticError" },
+    selectedLineBgColor        = { bg = "Visual" }, -- set to `default` to have no background colour
+    unstagedChangesColor       = { fg = "DiagnosticError" },
   },
   win = {
     style = "lazygit",

lua/snacks/notifier.lua

@@ -65,7 +65,7 @@ M.styles = {
 ---@class snacks.notifier.Config
 ---@field keep? fun(notif: snacks.notifier.Notif): boolean
 local defaults = {
-  timeout = 3000,
+  timeout = 3000, -- default timeout in ms
   width = { min = 40, max = 0.4 },
   height = { min = 1, max = 0.6 },
   padding = true, -- add 1 cell of left/right padding to the notification window

lua/snacks/statuscolumn.lua

@@ -9,13 +9,14 @@ local M = setmetatable({}, {
 
 ---@class snacks.statuscolumn.Config
 local defaults = {
-  left = { "mark", "sign" },
-  right = { "fold", "git" },
+  left = { "mark", "sign" }, -- priority of signs on the left (high to low)
+  right = { "fold", "git" }, -- priority of signs on the right (high to low)
   folds = {
     open = false, -- show open fold icons
     git_hl = false, -- use Git Signs hl for fold icons
   },
   git = {
+    -- patterns to match Git signs
     patterns = { "GitSign", "MiniDiffSign" },
   },
   refresh = 50, -- refresh at most every 50ms

lua/snacks/toggle.lua

@@ -11,13 +11,15 @@ local M = setmetatable({}, {
 ---@field icon? string|{ enabled: string, disabled: string }
 ---@field color? string|{ enabled: string, disabled: string }
 local defaults = {
-  map = vim.keymap.set,
-  which_key = true,
-  notify = true,
+  map = vim.keymap.set, -- keymap.set function to use
+  which_key = true, -- integrate with which-key to show enabled/disabled icons and colors
+  notify = true, -- show a notification when toggling
+  -- icons for enabled/disabled states
   icon = {
     enabled = " ",
     disabled = " ",
   },
+  -- colors for enabled/disabled states
   color = {
     enabled = "green",
     disabled = "yellow",

lua/snacks/win.lua

@@ -18,20 +18,19 @@ local M = setmetatable({}, {
 ---@field mode? string|string[]
 
 ---@class snacks.win.Config: vim.api.keyset.win_config
----@field style? string merges with config from `Snacks.config.views[view]`
+---@field style? string merges with config from `Snacks.config.styles[style]`
 ---@field show? boolean Show the window immediately (default: true)
----@field minimal? boolean
+---@field minimal? boolean Disable a bunch of options to make the window minimal (default: true)
 ---@field position? "float"|"bottom"|"top"|"left"|"right"
----@field buf? number
----@field file? string
----@field enter? boolean
----@field backdrop? number|false
----@field win? vim.api.keyset.win_config
----@field wo? vim.wo
----@field bo? vim.bo
----@field keys? table<string, false|string|fun(self: snacks.win)|snacks.win.Keys>
----@field on_buf? fun(self: snacks.win)
----@field on_win? fun(self: snacks.win)
+---@field buf? number If set, use this buffer instead of creating a new one
+---@field file? string If set, use this file instead of creating a new buffer
+---@field enter? boolean Enter the window after opening (default: false)
+---@field backdrop? number|false Opacity of the backdrop (default: 60)
+---@field wo? vim.wo window options
+---@field bo? vim.bo buffer options
+---@field keys? table<string, false|string|fun(self: snacks.win)|snacks.win.Keys> Key mappings
+---@field on_buf? fun(self: snacks.win) Callback after opening the buffer
+---@field on_win? fun(self: snacks.win) Callback after opening the window
 local defaults = {
   show = true,
   relative = "editor",

lua/snacks/words.lua

@@ -7,8 +7,8 @@ local M = {}
 
 ---@class snacks.words.Config
 local defaults = {
-  enabled = true,
-  debounce = 200,
+  enabled = true, -- enable/disable the plugin
+  debounce = 200, -- time in ms to wait before updating
 }
 
 local config = Snacks.config.get("words", defaults)