enhance/doc: rename refresh_opts.kind to scope.

document lualine.refresh()
apply defaults to refresh_opts

README.md

@@ -842,6 +842,27 @@ require('lualine').setup { extensions = { my_extension } }
 
 ---
 
+### Refreshing lualine
+By default lualine refreshes itself based on timer and some events. You can set
+the interval of the timer with refresh option. However you can also force
+lualine to refresh at any time by calling lualine.refresh function.
+```lua
+require('lualine').refresh({
+  scope = 'tabpage',  -- scope of refresh all/tabpage/window
+  place = { 'statusline', 'winbar', 'tabline' },  -- lualine segment ro refresh.
+})
+```
+The arguments shown here are default values. So not passing any of them will be
+treated as if a default value was passed.
+
+So you can simply do
+```lua
+require('lualine').refresh()
+```
+
+Avoid calling lualine.refresh inside components. Since components are evaluated
+during refresh, calling refresh while refreshing can have undesirable effects.
+
 ### Disabling lualine
 
 You can disable lualine for specific filetypes:

doc/lualine.txt

@@ -895,6 +895,34 @@ Custom extensions                      You can define your own extensions. If
 
 ------------------------------------------------------------------------------
 
+REFRESHING LUALINE ~
+
+By default lualine refreshes itself based on timer and some events. You can set
+the interval of the timer with refresh option. However you can also force
+lualine to refresh at any time by calling lualine.refresh function.
+
+>
+    require('lualine').refresh({
+      scope = 'tabpage',  -- scope of refresh all/tabpage/window
+      place = { 'statusline', 'winbar', 'tabline' },  -- lualine segment ro refresh.
+    })
+<
+
+
+The arguments shown here are default values. So not passing any of them will be
+treated as if a default value was passed.
+
+So you can simply do
+
+>
+    require('lualine').refresh()
+<
+
+
+to refresh. Also don’t call refresh inside components. As components are
+evaluated during refresh, calling refresh while refreshing can have undesirable
+effects.
+
 DISABLING LUALINE ~
 
 You can disable lualine for specific filetypes:

lua/lualine.lua

@@ -306,15 +306,20 @@ end
 ---| 'tabline'
 ---| 'winbar'
 ---@class LualineRefreshOpts
----@field kind LualineRefreshOptsKind
+---@field scope LualineRefreshOptsKind
 ---@field place LualineRefreshOptsPlace[]
 ---@field trigger 'autocmd'|'autocmd_redired'|'timer'|'unknown'
 --- Refresh contents of lualine
 ---@param opts LualineRefreshOpts
 local function refresh(opts)
   if opts == nil then
-    opts = { kind = 'tabpage', place = { 'statusline', 'winbar', 'tabline' }, trigger = 'unknown' }
+    opts = {}
   end
+  opts = vim.tbl_extend('keep', opts, {
+    scope = 'tabpage',
+    place = { 'statusline', 'winbar', 'tabline' },
+    trigger = 'unknown'
+  })
 
   -- updating statusline in autocommands context seems to trigger 100 different bugs
   -- lets just defer it to a timer context and update there
@@ -378,19 +383,19 @@ local function refresh(opts)
   vim.g.actual_curwin = last_focus[curtab]
 
   -- gather which windows needs update
-  if opts.kind == 'all' then
+  if opts.scope == 'all' then
     if vim.tbl_contains(opts.place, 'statusline') or vim.tbl_contains(opts.place, 'winbar') then
       wins = vim.tbl_filter(function(win)
         return vim.fn.win_gettype(win) ~= 'popup'
       end, vim.api.nvim_list_wins())
     end
-  elseif opts.kind == 'tabpage' then
+  elseif opts.scope == 'tabpage' then
     if vim.tbl_contains(opts.place, 'statusline') or vim.tbl_contains(opts.place, 'winbar') then
       wins = vim.tbl_filter(function(win)
         return vim.fn.win_gettype(win) ~= 'popup'
       end, vim.api.nvim_tabpage_list_wins(0))
     end
-  elseif opts.kind == 'window' then
+  elseif opts.scope == 'window' then
     wins = { curwin }
   end