docs: api, messages, lsp, trust

gen_vimdoc.lua: In prepare for the upcoming release, comment-out the
"Experimental" warning for prerelease features.

runtime/example_init.lua

@@ -3,17 +3,18 @@
 -- NOTE: Must happen before plugins are loaded (otherwise wrong leader will be used)
 vim.g.mapleader = ' '
 
--- [[ Setting options ]] See `:h vim.o`
+-- OPTIONS
+--
+-- See `:h vim.o`
 -- NOTE: You can change these options as you wish!
 -- For more options, you can see `:help option-list`
 -- To see documentation for an option, you can use `:h 'optionname'`, for example `:h 'number'`
 -- (Note the single quotes)
 
--- Print the line number in front of each line
-vim.o.number = true
+vim.o.number = true -- Show line numbers in a column.
 
--- Use relative line numbers, so that it is easier to jump with j, k. This will affect the 'number'
--- option above, see `:h number_relativenumber`
+-- Show line numbers relative to where the cursor is.
+-- Affects the 'number' option above, see `:h number_relativenumber`.
 vim.o.relativenumber = true
 
 -- Sync clipboard between OS and Neovim. Schedule the setting after `UIEnter` because it can
@@ -29,20 +30,17 @@ vim.api.nvim_create_autocmd('UIEnter', {
 vim.o.ignorecase = true
 vim.o.smartcase = true
 
--- Highlight the line where the cursor is on
-vim.o.cursorline = true
-
--- Minimal number of screen lines to keep above and below the cursor.
-vim.o.scrolloff = 10
-
--- Show <tab> and trailing spaces
-vim.o.list = true
+vim.o.cursorline = true -- Highlight the line where the cursor is on.
+vim.o.scrolloff = 10 -- Keep this many screen lines above/below the cursor.
+vim.o.list = true -- Show <tab> and trailing spaces.
 
 -- if performing an operation that would fail due to unsaved changes in the buffer (like `:q`),
 -- instead raise a dialog asking if you wish to save the current file(s) See `:help 'confirm'`
 vim.o.confirm = true
 
--- [[ Set up keymaps ]] See `:h vim.keymap.set()`, `:h mapping`, `:h keycodes`
+-- KEYMAPS
+--
+-- See `:h vim.keymap.set()`, `:h mapping`, `:h keycodes`
 
 -- Use <Esc> to exit terminal mode
 vim.keymap.set('t', '<Esc>', '<C-\\><C-n>')
@@ -57,7 +55,8 @@ vim.keymap.set({ 'n' }, '<A-j>', '<C-w>j')
 vim.keymap.set({ 'n' }, '<A-k>', '<C-w>k')
 vim.keymap.set({ 'n' }, '<A-l>', '<C-w>l')
 
--- [[ Basic Autocommands ]].
+-- AUTOCOMMANDS (EVENT HANDLERS)
+--
 -- See `:h lua-guide-autocommands`, `:h autocmd`, `:h nvim_create_autocmd()`
 
 -- Highlight when yanking (copying) text.
@@ -69,7 +68,8 @@ vim.api.nvim_create_autocmd('TextYankPost', {
   end,
 })
 
--- [[ Create user commands ]]
+-- USER COMMANDS: DEFINE CUSTOM COMMANDS
+--
 -- See `:h nvim_create_user_command()` and `:h user-commands`
 
 -- Create a command `:GitBlameLine` that print the git blame for the current line
@@ -79,15 +79,24 @@ vim.api.nvim_create_user_command('GitBlameLine', function()
   print(vim.system({ 'git', 'blame', '-L', line_number .. ',+1', filename }):wait().stdout)
 end, { desc = 'Print the git blame for the current line' })
 
--- [[ Add optional packages ]]
--- Nvim comes bundled with a set of packages that are not enabled by
--- default. You can enable any of them by using the `:packadd` command.
+-- PLUGINS
+--
+-- * Enable optional, builtin plugins via ":packadd".
+-- * Install third-party plugins via "vim.pack".
 
--- For example, to add the "nohlsearch" package to automatically turn off search highlighting after
--- 'updatetime' and when going to insert mode
+-- Example: add the "nohlsearch" package to automatically disable search highlighting after
+-- 'updatetime' and when going to insert mode.
 vim.cmd('packadd! nohlsearch')
 
--- [[ Install plugins ]]
--- Nvim functionality can be extended by installing external plugins.
--- One way to do it is with a built-in plugin manager. See `:h vim.pack`.
-vim.pack.add({ 'https://github.com/neovim/nvim-lspconfig' })
+-- Example: Install third-party plugins by calling "vim.pack.add{}".
+vim.pack.add({
+  'https://github.com/neovim/nvim-lspconfig',
+  -- Fuzzy picker
+  'https://github.com/ibhagwan/fzf-lua',
+  -- Autocompletion
+  'https://github.com/echasnovski/mini.completion',
+  -- Enhanced quickfix/loclist
+  'https://github.com/stevearc/quicker.nvim',
+  -- Git integration
+  'https://github.com/lewis6991/gitsigns.nvim',
+})