docs(gen): support language annotation in docstrings

6 files changed, 153 insertions, 154 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 0eccb64517..a8433640ab 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -803,7 +803,7 @@ nvim_feedkeys({keys}, {mode}, {escape_ks})                   *nvim_feedkeys()*
     with escape_ks=false) to replace |keycodes|, then pass the result to
     nvim_feedkeys().
 
-    Example: >
+    Example: >vim
         :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
         :call nvim_feedkeys(key, 'n', v:false)
 <
@@ -859,7 +859,7 @@ nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
     Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
     "#rrggbb" hexadecimal string.
 
-    Example: >
+    Example: >vim
         :echo nvim_get_color_by_name("Pink")
         :echo nvim_get_color_by_name("#cbcbcb")
 <
@@ -1444,11 +1444,11 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
     Unlike |:map|, leading/trailing whitespace is accepted as part of the
     {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
 
-    Example: >
+    Example: >vim
         call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
 <
 
-    is equivalent to: >
+    is equivalent to: >vim
         nmap <nowait> <Space><NL> <Nop>
 <
 
@@ -1746,7 +1746,7 @@ nvim_create_user_command({name}, {command}, {*opts})
 
     {command} is the replacement text or Lua function to execute.
 
-    Example: >
+    Example: >vim
        :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
        :SayHello
        Hello world!
@@ -2027,7 +2027,7 @@ whether a buffer is loaded.
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
     Activates buffer-update events on a channel, or as Lua callbacks.
 
-    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >
+    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
       events = {}
       vim.api.nvim_buf_attach(0, false, {
         on_lines=function(...) table.insert(events, {...}) end})
@@ -2529,29 +2529,27 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
 
     Region can be given as (row,col) tuples, or valid extmark ids (whose
     positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
-    respectively, thus the following are equivalent:
->
-    nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
-    nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
+    respectively, thus the following are equivalent: >lua
+      nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+      nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
 <
 
     If `end` is less than `start`, traversal works backwards. (Useful with
     `limit`, to get the first marks prior to a given position.)
 
-    Example:
->
-    local a   = vim.api
-    local pos = a.nvim_win_get_cursor(0)
-    local ns  = a.nvim_create_namespace('my-plugin')
-    -- Create new extmark at line 1, column 1.
-    local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
-    -- Create new extmark at line 3, column 1.
-    local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
-    -- Get extmarks only from line 3.
-    local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-    -- Get all marks in this buffer + namespace.
-    local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-    print(vim.inspect(ms))
+    Example: >lua
+      local a   = vim.api
+      local pos = a.nvim_win_get_cursor(0)
+      local ns  = a.nvim_create_namespace('my-plugin')
+      -- Create new extmark at line 1, column 1.
+      local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
+      -- Create new extmark at line 3, column 1.
+      local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
+      -- Get extmarks only from line 3.
+      local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
+      -- Get all marks in this buffer + namespace.
+      local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
+      print(vim.inspect(ms))
 <
 
     Parameters: ~
@@ -2969,12 +2967,12 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
     could let floats hover outside of the main window like a tooltip, but this
     should not be used to specify arbitrary WM screen positions.
 
-    Example (Lua): window-relative float >
+    Example (Lua): window-relative float >lua
         vim.api.nvim_open_win(0, false,
           {relative='win', row=3, col=3, width=12, height=3})
 <
 
-    Example (Lua): buffer-relative float (travels as buffer is scrolled) >
+    Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua
         vim.api.nvim_open_win(0, false,
           {relative='win', width=12, height=3, bufpos={100,10}})
 <
@@ -3210,7 +3208,7 @@ nvim_clear_autocmds({*opts})                           *nvim_clear_autocmds()*
 nvim_create_augroup({name}, {*opts})                   *nvim_create_augroup()*
     Create or get an autocommand group |autocmd-groups|.
 
-    To get an existing group id, do: >
+    To get an existing group id, do: >lua
         local id = vim.api.nvim_create_augroup("MyGroup", {
             clear = false
         })
@@ -3235,7 +3233,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
     executed when the autocommand triggers: a callback function (Lua or
     Vimscript), or a command (like regular autocommands).
 
-    Example using callback: >
+    Example using callback: >lua
         -- Lua function
         local myluafun = function() print("This buffer enters") end
 
@@ -3250,40 +3248,39 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
 
     Lua functions receive a table with information about the autocmd event as
     an argument. To use a function which itself accepts another (optional)
-    parameter, wrap the function in a lambda:
->
-    -- Lua function with an optional parameter.
-    -- The autocmd callback would pass a table as argument but this
-    -- function expects number|nil
-    local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
-
-    vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-      pattern = {"*.c", "*.h"},
-      callback = function() myluafun() end,
-    })
+    parameter, wrap the function in a lambda: >lua
+        -- Lua function with an optional parameter.
+        -- The autocmd callback would pass a table as argument but this
+        -- function expects number|nil
+        local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
+
+        vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+          pattern = {"*.c", "*.h"},
+          callback = function() myluafun() end,
+        })
 <
 
-    Example using command: >
+    Example using command: >lua
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
           command = "echo 'Entering a C or C++ file'",
         })
 <
 
-    Example values for pattern: >
+    Example values for pattern: >lua
       pattern = "*.py"
       pattern = { "*.py", "*.pyi" }
 <
 
     Note: The `pattern` is passed to callbacks and commands as a literal string; environment
     variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
-    |expand()| such variables explicitly: >
+    |expand()| such variables explicitly: >lua
       pattern = vim.fn.expand("~") .. "/some/path/*.py"
 <
 
-    Example values for event: >
-      "BufWritePre"
-      {"CursorHold", "BufWritePre", "BufWritePost"}
+    Example values for event: >lua
+      event = "BufWritePre"
+      event = {"CursorHold", "BufWritePre", "BufWritePost"}
 <
 
     Parameters: ~
@@ -3394,7 +3391,7 @@ nvim_exec_autocmds({event}, {*opts})                    *nvim_exec_autocmds()*
 nvim_get_autocmds({*opts})                               *nvim_get_autocmds()*
     Get all autocommands that match the corresponding {opts}.
 
-    These examples will get autocommands matching ALL the given criteria: >
+    These examples will get autocommands matching ALL the given criteria: >lua
       -- Matches all criteria
       autocommands = vim.api.nvim_get_autocmds({
         group = "MyGroup",
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 6862426b1b..9336321d73 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -185,6 +185,7 @@ Docstring format:
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>` for code samples.
+  Code samples can be annotated as `vim` or `lua`
 
 Example: the help for |nvim_open_win()| is generated from a docstring defined
 in src/nvim/api/win_config.c like this: >
@@ -193,7 +194,7 @@ in src/nvim/api/win_config.c like this: >
     /// ...
     ///
     /// Example (Lua): window-relative float
-    /// <pre>
+    /// <pre>lua
     ///     vim.api.nvim_open_win(0, false,
     ///       {relative='win', row=3, col=3, width=12, height=3})
     /// </pre>
@@ -223,6 +224,7 @@ Docstring format:
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>` for code samples.
+  Code samples can be annotated as `vim` or `lua`
 
 Example: the help for |vim.paste()| is generated from a docstring decorating
 vim.paste in runtime/lua/vim/_editor.lua like this: >
@@ -231,7 +233,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     --- (such as the |TUI|) pastes text into the editor.
     ---
     --- Example: To remove ANSI color codes when pasting:
-    --- <pre>
+    --- <pre>lua
     --- vim.paste = (function()
     ---   local overridden = vim.paste
     ---   ...
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 56c2af10b4..457a41dc08 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -320,12 +320,12 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
     |vim.diagnostic.show()|). Ephemeral configuration has highest priority,
     followed by namespace configuration, and finally global configuration.
 
-    For example, if a user enables virtual text globally with >
+    For example, if a user enables virtual text globally with >lua
 
        vim.diagnostic.config({ virtual_text = true })
 <
 
-    and a diagnostic producer sets diagnostics with >
+    and a diagnostic producer sets diagnostics with >lua
 
        vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
 <
@@ -372,14 +372,14 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
                          to render an LSP diagnostic error code.
                        • format: (function) A function that takes a diagnostic
                          as input and returns a string. The return value is
-                         the text used to display the diagnostic. Example: >
+                         the text used to display the diagnostic. Example: >lua
 
-                           function(diagnostic)
-                             if diagnostic.severity == vim.diagnostic.severity.ERROR then
-                               return string.format("E: %s", diagnostic.message)
+                             function(diagnostic)
+                               if diagnostic.severity == vim.diagnostic.severity.ERROR then
+                                 return string.format("E: %s", diagnostic.message)
+                               end
+                               return diagnostic.message
                              end
-                             return diagnostic.message
-                           end
 <
 
                      • signs: (default true) Use signs for diagnostics.
@@ -553,12 +553,12 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
      WARNING filename:27:3: Variable 'foo' does not exist
 <
 
-    This can be parsed into a diagnostic |diagnostic-structure| with: >
+    This can be parsed into a diagnostic |diagnostic-structure| with: >lua
 
-     local s = "WARNING filename:27:3: Variable 'foo' does not exist"
-     local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
-     local groups = { "severity", "lnum", "col", "message" }
-     vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
+       local s = "WARNING filename:27:3: Variable 'foo' does not exist"
+       local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
+       local groups = { "severity", "lnum", "col", "message" }
+       vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
 <
 
     Parameters: ~
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 06c0f466e7..4c4403c38f 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -681,7 +681,7 @@ for_each_buffer_client({bufnr}, {fn})
       • {bufnr}  (number) Buffer number
       • {fn}     (function) Function to run on each client attached to buffer
                  {bufnr}. The function takes the client, client ID, and buffer
-                 number as arguments. Example: >
+                 number as arguments. Example: >lua
 
                    vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
                      print(vim.inspect(client))
@@ -780,14 +780,13 @@ start({config}, {opts})                                      *vim.lsp.start()*
     running client if one is found matching `name` and `root_dir`. Attaches
     the current buffer to the client.
 
-    Example:
->
+    Example: >lua
 
-    vim.lsp.start({
-       name = 'my-server-name',
-       cmd = {'name-of-language-server-executable'},
-       root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
-    })
+     vim.lsp.start({
+        name = 'my-server-name',
+        cmd = {'name-of-language-server-executable'},
+        root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
+     })
 <
 
     See |vim.lsp.start_client()| for all available options. The most important
@@ -964,11 +963,9 @@ start_client({config})                                *vim.lsp.start_client()*
 stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
     Stops a client(s).
 
-    You can also use the `stop()` function on a |vim.lsp.client| object. To
-    stop all clients:
->
+    You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua
 
-    vim.lsp.stop_client(vim.lsp.get_active_clients())
+     vim.lsp.stop_client(vim.lsp.get_active_clients())
 <
 
     By default asks the server to shutdown, unless stop was requested already
@@ -1078,11 +1075,10 @@ definition({options})                               *vim.lsp.buf.definition()*
 document_highlight()                        *vim.lsp.buf.document_highlight()*
     Send request to the server to resolve document highlights for the current
     text document position. This request can be triggered by a key mapping or
-    by events such as `CursorHold`, e.g.:
->
-    autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
-    autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
-    autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
+    by events such as `CursorHold` , e.g.: >vim
+      autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
+      autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
+      autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
 <
 
     Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
@@ -1126,12 +1122,12 @@ format({options})                                       *vim.lsp.buf.format()*
                      buffer (0).
                    • filter (function|nil): Predicate used to filter clients.
                      Receives a client as argument and must return a boolean.
-                     Clients matching the predicate are included. Example:               • >
+                     Clients matching the predicate are included. Example:               • >lua
 
-            -- Never request typescript-language-server for formatting
-            vim.lsp.buf.format {
-              filter = function(client) return client.name ~= "tsserver" end
-            }
+              -- Never request typescript-language-server for formatting
+              vim.lsp.buf.format {
+                filter = function(client) return client.name ~= "tsserver" end
+              }
 <
                    • async boolean|nil If true the method won't block.
                      Defaults to false. Editing the buffer while formatting
@@ -1253,7 +1249,7 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
     |lsp-handler| for the method "textDocument/publishDiagnostics"
 
     See |vim.diagnostic.config()| for configuration options. Handler-specific
-    configuration can be set using |vim.lsp.with()|: >
+    configuration can be set using |vim.lsp.with()|: >lua
 
      vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
        vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -1306,8 +1302,9 @@ refresh()                                         *vim.lsp.codelens.refresh()*
     Refresh the codelens for the current buffer
 
     It is recommended to trigger this using an autocmd or via keymap.
->
-    autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
+
+    Example: >vim
+      autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
 <
 
 run()                                                 *vim.lsp.codelens.run()*
@@ -1326,16 +1323,16 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
 Lua module: vim.lsp.handlers                                    *lsp-handlers*
 
 hover({_}, {result}, {ctx}, {config})               *vim.lsp.handlers.hover()*
-    |lsp-handler| for the method "textDocument/hover" >
-
-     vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
-       vim.lsp.handlers.hover, {
-         -- Use a sharp border with `FloatBorder` highlights
-         border = "single",
-         -- add the title in hover float window
-         title = "hover"
-       }
-     )
+    |lsp-handler| for the method "textDocument/hover" >lua
+
+       vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
+         vim.lsp.handlers.hover, {
+           -- Use a sharp border with `FloatBorder` highlights
+           border = "single",
+           -- add the title in hover float window
+           title = "hover"
+         }
+       )
 <
 
     Parameters: ~
@@ -1347,14 +1344,14 @@ hover({_}, {result}, {ctx}, {config})               *vim.lsp.handlers.hover()*
                                            *vim.lsp.handlers.signature_help()*
 signature_help({_}, {result}, {ctx}, {config})
     |lsp-handler| for the method "textDocument/signatureHelp". The active
-    parameter is highlighted with |hl-LspSignatureActiveParameter|. >
-
-     vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
-       vim.lsp.handlers.signature_help, {
-         -- Use a sharp border with `FloatBorder` highlights
-         border = "single"
-       }
-     )
+    parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
+
+       vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
+         vim.lsp.handlers.signature_help, {
+           -- Use a sharp border with `FloatBorder` highlights
+           border = "single"
+         }
+       )
 <
 
     Parameters: ~
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 1c381bd956..a5e99ae162 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1302,7 +1302,7 @@ cmd({command})                                                     *vim.cmd()*
     Note that `vim.cmd` can be indexed with a command name to return a
     callable function to the command.
 
-    Example: >
+    Example: >lua
 
        vim.cmd('echo 42')
        vim.cmd([[
@@ -1436,7 +1436,7 @@ paste({lines}, {phase})                                          *vim.paste()*
     Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
     |TUI|) pastes text into the editor.
 
-    Example: To remove ANSI color codes when pasting: >
+    Example: To remove ANSI color codes when pasting: >lua
 
      vim.paste = (function(overridden)
        return function(lines, phase)
@@ -1465,7 +1465,7 @@ paste({lines}, {phase})                                          *vim.paste()*
         |paste| @alias paste_phase -1 | 1 | 2 | 3
 
 pretty_print({...})                                       *vim.pretty_print()*
-    Prints given arguments in human-readable format. Example: >
+    Prints given arguments in human-readable format. Example: >lua
       -- Print highlight group Normal and store it's contents in a variable.
       local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
 <
@@ -1544,10 +1544,11 @@ defaulttable({create})                                    *vim.defaulttable()*
     If {create} is `nil`, this will create a defaulttable whose constructor
     function is this function, effectively allowing to create nested tables on
     the fly:
->
 
-    local a = vim.defaulttable()
-    a.b.c = 1
+    >lua
+
+     local a = vim.defaulttable()
+     a.b.c = 1
 <
 
     Parameters: ~
@@ -1637,12 +1638,12 @@ pesc({s})                                                         *vim.pesc()*
 split({s}, {sep}, {kwargs})                                      *vim.split()*
     Splits a string at each instance of a separator.
 
-    Examples: >
+    Examples: >lua
 
-      split(":aa::b:", ":")     => {'','aa','','b',''}
-      split("axaby", "ab?")     => {'','x','y'}
-      split("x*yz*o", "*", {plain=true})  => {'x','yz','o'}
-      split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
+      split(":aa::b:", ":")                   --> {'','aa','','b',''}
+      split("axaby", "ab?")                   --> {'','x','y'}
+      split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
+      split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 <
 
     Parameters: ~
@@ -1695,10 +1696,11 @@ tbl_contains({t}, {value})                                *vim.tbl_contains()*
 
 tbl_count({t})                                               *vim.tbl_count()*
     Counts the number of non-nil values in table `t`.
->
 
-    vim.tbl_count({ a=1, b=2 }) => 2
-    vim.tbl_count({ 1, 2 }) => 2
+    >lua
+
+     vim.tbl_count({ a=1, b=2 })  --> 2
+     vim.tbl_count({ 1, 2 })      --> 2
 <
 
     Parameters: ~
@@ -1771,7 +1773,7 @@ tbl_get({o}, {...})                                            *vim.tbl_get()*
     Index into a table (first argument) via string keys passed as subsequent
     arguments. Return `nil` if the key does not exist.
 
-    Examples: >
+    Examples: >lua
 
       vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
       vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
@@ -1858,7 +1860,7 @@ trim({s})                                                         *vim.trim()*
 validate({opt})                                               *vim.validate()*
     Validates a parameter specification (types and values).
 
-    Usage example: >
+    Usage example: >lua
 
       function user.new(name, age, hobbies)
         vim.validate{
@@ -1870,25 +1872,25 @@ validate({opt})                                               *vim.validate()*
       end
 <
 
-    Examples with explicit argument values (can be run directly): >
+    Examples with explicit argument values (can be run directly): >lua
 
       vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
-         => NOP (success)
+         --> NOP (success)
 
       vim.validate{arg1={1, 'table'}}
-         => error('arg1: expected table, got number')
+         --> error('arg1: expected table, got number')
 
       vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
-         => error('arg1: expected even number, got 3')
+         --> error('arg1: expected even number, got 3')
 <
 
-    If multiple types are valid they can be given as a list. >
+    If multiple types are valid they can be given as a list. >lua
 
       vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
-         => NOP (success)
+         --> NOP (success)
 
       vim.validate{arg1={1, {'string', table'}}}
-         => error('arg1: expected string|table, got number')
+         --> error('arg1: expected string|table, got number')
 <
 
     Parameters: ~
@@ -1957,7 +1959,7 @@ Lua module: ui                                                        *lua-ui*
 input({opts}, {on_confirm})                                   *vim.ui.input()*
     Prompts the user for input
 
-    Example: >
+    Example: >lua
 
      vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
          vim.o.shiftwidth = tonumber(input)
@@ -1982,7 +1984,7 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
 select({items}, {opts}, {on_choice})                         *vim.ui.select()*
     Prompts the user to pick a single item from a collection of entries
 
-    Example: >
+    Example: >lua
 
      vim.ui.select({ 'tabs', 'spaces' }, {
          prompt = 'Select tabs or spaces:',
@@ -2045,7 +2047,7 @@ add({filetypes})                                          *vim.filetype.add()*
 
     See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
 
-    Example: >
+    Example: >lua
 
       vim.filetype.add({
         extension = {
@@ -2081,7 +2083,7 @@ add({filetypes})                                          *vim.filetype.add()*
       })
 <
 
-    To add a fallback match on contents, use >
+    To add a fallback match on contents, use >lua
 
      vim.filetype.add {
        pattern = {
@@ -2120,19 +2122,20 @@ match({args})                                           *vim.filetype.match()*
 
     Each of the three options is specified using a key to the single argument
     of this function. Example:
->
 
-    -- Using a buffer number
-    vim.filetype.match({ buf = 42 })
+    >lua
+
+       -- Using a buffer number
+       vim.filetype.match({ buf = 42 })
 
-    -- Override the filename of the given buffer
-    vim.filetype.match({ buf = 42, filename = 'foo.c' })
+       -- Override the filename of the given buffer
+       vim.filetype.match({ buf = 42, filename = 'foo.c' })
 
-    -- Using a filename without a buffer
-    vim.filetype.match({ filename = 'main.lua' })
+       -- Using a filename without a buffer
+       vim.filetype.match({ filename = 'main.lua' })
 
-    -- Using file contents
-    vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
+       -- Using file contents
+       vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
 <
 
     Parameters: ~
@@ -2162,7 +2165,7 @@ match({args})                                           *vim.filetype.match()*
 Lua module: keymap                                                *lua-keymap*
 
 del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
-    Remove an existing mapping. Examples: >
+    Remove an existing mapping. Examples: >lua
 
        vim.keymap.del('n', 'lhs')
 
@@ -2178,7 +2181,7 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
         |vim.keymap.set()|
 
 set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
-    Add a new |mapping|. Examples: >
+    Add a new |mapping|. Examples: >lua
 
        -- Can add mapping to Lua functions
        vim.keymap.set('n', 'lhs', function() print("real lua function") end)
@@ -2197,14 +2200,14 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
        vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
 <
 
-    Note that in a mapping like: >
+    Note that in a mapping like: >lua
 
         vim.keymap.set('n', 'asdf', require('jkl').my_fun)
 <
 
     the `require('jkl')` gets evaluated during this call in order to access the function. If you
     want to avoid this cost at startup you can wrap it in a function, for
-    example: >
+    example: >lua
 
         vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 <
@@ -2302,8 +2305,8 @@ find({names}, {opts})                                          *vim.fs.find()*
                    number of matches.
 
     Return: ~
-        (table) The normalized paths |vim.fs.normalize()| of all matching
-        files or directories
+        (table) Normalized paths |vim.fs.normalize()| of all matching files or
+        directories
 
 normalize({path})                                         *vim.fs.normalize()*
     Normalize a path to a standard format. A tilde (~) character at the
@@ -2311,16 +2314,16 @@ normalize({path})                                         *vim.fs.normalize()*
     backslash (\) characters are converted to forward slashes (/). Environment
     variables are also expanded.
 
-    Examples: >
+    Examples: >lua
 
        vim.fs.normalize('C:\Users\jdoe')
-       => 'C:/Users/jdoe'
+       --> 'C:/Users/jdoe'
 
        vim.fs.normalize('~/src/neovim')
-       => '/home/jdoe/src/neovim'
+       --> '/home/jdoe/src/neovim'
 
        vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
-       => '/Users/jdoe/.config/nvim/init.vim'
+       --> '/Users/jdoe/.config/nvim/init.vim'
 <
 
     Parameters: ~
@@ -2332,7 +2335,7 @@ normalize({path})                                         *vim.fs.normalize()*
 parents({start})                                            *vim.fs.parents()*
     Iterate over all the parents of the given file or directory.
 
-    Example: >
+    Example: >lua
 
      local root_dir
      for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index cef48e207f..2a826e90e5 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -605,7 +605,7 @@ start({bufnr}, {lang})                                               *start()*
     required for some plugins. In this case, add `vim.bo.syntax = 'on'` after
     the call to `start`.
 
-    Example: >
+    Example: >lua
 
      vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
          callback = function(args)
@@ -770,7 +770,7 @@ Query:iter_captures({self}, {node}, {source}, {start}, {stop})
 
     The iterator returns three values: a numeric id identifying the capture,
     the captured node, and metadata from any directives processing the match.
-    The following example shows how to get captures by name: >
+    The following example shows how to get captures by name: >lua
 
      for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
        local name = query.captures[id] -- name of the capture in the query
@@ -802,7 +802,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
     (1-based) index of the pattern in the query, a table mapping capture
     indices to nodes, and metadata from any directives processing the match.
     If the query has more than one pattern, the capture table might be sparse
-    and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >
+    and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >lua
 
      for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
        for id, node in pairs(match) do