docs: improve example in incremental preview section (#19613)

- Separate preview and callback functions to make the example easier to understand
- Use false instead of 0 for boolean arguments in API function calls
- Remove explicit nil checks for consistency
- Format with stylua

1 files changed, 53 insertions, 48 deletions

diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 1e1f4e46af..b0ce2d4164 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1483,74 +1483,79 @@ in the preview namespace.
 Here's an example of a command to trim trailing whitespace from lines that
 supports incremental command preview:
 >
-	-- Trims trailing whitespace in the current buffer.
-	-- Also performs 'inccommand' preview if invoked as a preview callback
-	-- (preview_ns is non-nil).
-	local function trim_space(opts, preview_ns, preview_buf)
+	-- If invoked as a preview callback, performs 'inccommand' preview by
+	-- highlighting trailing whitespace in the current buffer.
+	local function trim_space_preview(opts, preview_ns, preview_buf)
 	  local line1 = opts.line1
 	  local line2 = opts.line2
 	  local buf = vim.api.nvim_get_current_buf()
-	  local lines = vim.api.nvim_buf_get_lines(buf, line1 - 1, line2, 0)
-	  local new_lines = {}
+	  local lines = vim.api.nvim_buf_get_lines(buf, line1 - 1, line2, false)
 	  local preview_buf_line = 0
 
 	  for i, line in ipairs(lines) do
-	    local startidx, endidx = string.find(line, '%s+$')
-
-	    if startidx ~= nil then
-	      -- Highlight the match if in command preview mode
-	      if preview_ns ~= nil then
-		vim.api.nvim_buf_add_highlight(
-		  buf, preview_ns, 'Substitute', line1 + i - 2, startidx - 1,
-		  endidx
-		)
-
-		-- Add lines and highlight to the preview buffer
-		-- if inccommand=split
-		if preview_buf ~= nil then
-		  local prefix = string.format('|%d| ', line1 + i - 1)
-
-		  vim.api.nvim_buf_set_lines(
-		    preview_buf, preview_buf_line, preview_buf_line, 0,
-		    { prefix .. line }
-		  )
-		  vim.api.nvim_buf_add_highlight(
-		    preview_buf, preview_ns, 'Substitute', preview_buf_line,
-		    #prefix + startidx - 1, #prefix + endidx
-		  )
-
-		  preview_buf_line = preview_buf_line + 1
-		end
+	    local start_idx, end_idx = string.find(line, '%s+$')
+
+	    if start_idx then
+	      -- Highlight the match
+	      vim.api.nvim_buf_add_highlight(
+	        buf,
+	        preview_ns,
+	        'Substitute',
+	        line1 + i - 2,
+	        start_idx - 1,
+	        end_idx
+	      )
+
+	      -- Add lines and set highlights in the preview buffer
+	      -- if inccommand=split
+	      if preview_buf then
+	        local prefix = string.format('|%d| ', line1 + i - 1)
+
+	        vim.api.nvim_buf_set_lines(
+	          preview_buf,
+	          preview_buf_line,
+	          preview_buf_line,
+	          false,
+	          { prefix .. line }
+	        )
+	        vim.api.nvim_buf_add_highlight(
+	          preview_buf,
+	          preview_ns,
+	          'Substitute',
+	          preview_buf_line,
+	          #prefix + start_idx - 1,
+	          #prefix + end_idx
+	        )
+	        preview_buf_line = preview_buf_line + 1
 	      end
 	    end
-
-	    if not preview_ns then
-	      new_lines[#new_lines+1] = string.gsub(line, '%s+$', '')
-	    end
 	  end
 
-	  -- Don't make any changes to the buffer if previewing
-	  if not preview_ns then
-	    vim.api.nvim_buf_set_lines(buf, line1 - 1, line2, 0, new_lines)
-	  end
+	  -- Return the value of the preview type
+	  return 2
+	end
 
-	  -- When called as a preview callback, return the value of the
-	  -- preview type
-	  if preview_ns ~= nil then
-	    return 2
+	-- Trims all trailing whitespace in the current buffer.
+	local function trim_space(opts)
+	  local line1 = opts.line1
+	  local line2 = opts.line2
+	  local buf = vim.api.nvim_get_current_buf()
+	  local lines = vim.api.nvim_buf_get_lines(buf, line1 - 1, line2, false)
+
+	  local new_lines = {}
+	  for i, line in ipairs(lines) do
+	    new_lines[i] = string.gsub(line, '%s+$', '')
 	  end
+	  vim.api.nvim_buf_set_lines(buf, line1 - 1, line2, false, new_lines)
 	end
 
 	-- Create the user command
 	vim.api.nvim_create_user_command(
 	  'TrimTrailingWhitespace',
 	  trim_space,
-	  { nargs = '?', range = '%', addr = 'lines', preview = trim_space }
+	  { nargs = '?', range = '%', addr = 'lines', preview = trim_space_preview }
 	)
 <
-Note that in the above example, the same function is used as both the command
-callback and the preview callback, but you could instead use separate
-functions.
 
 
 Special cases ~