docs: naming conventions, guidelines

close #21063

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,15 +6,14 @@ body:
   - type: markdown
     attributes:
       value: |
-        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions such as "How do I...?" belong on the [Neovim Discourse](https://neovim.discourse.group/c/7-category/7) and will be closed.
+        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage or "How to" questions belong on the [stackoverflow](https://vi.stackexchange.com/) and will be closed.
 
   - type: textarea
     attributes:
-      label: "Describe the bug"
+      label: "Problem"
       description: "Describe the current behavior. May include logs, images, or videos."
     validations:
       required: true
-
   - type: textarea
     attributes:
       label: "Steps to reproduce"
@@ -27,7 +26,6 @@ body:
         yiwp
     validations:
       required: true
-
   - type: textarea
     attributes:
       label: "Expected behavior"

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Question
-    url: https://neovim.discourse.group/
+    url: https://vi.stackexchange.com/
     about: Ask questions about configuration and usage of Neovim

.github/ISSUE_TEMPLATE/lsp_bug_report.yml

@@ -6,27 +6,14 @@ body:
   - type: markdown
     attributes:
       value: |
-        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions such as "How do I...?" or "Why isn't X language server/feature working?" belong on the [Neovim Discourse](https://neovim.discourse.group/c/7-category/7) and will be closed.
+        _Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions or "Why isn't X language server/feature working?" belong on [stackoverflow](https://vi.stackexchange.com/) and will be closed.
 
-  - type: input
+  - type: textarea
     attributes:
-      label: "Neovim version (nvim -v)"
+      label: "Problem"
-      placeholder: "0.6.0 commit db1b0ee3b30f"
+      description: "Describe the bug caused by the Nvim LSP client."
     validations:
       required: true
-  - type: input
-    attributes:
-      label: "Language server name/version"
-      placeholder: "rls 0.5.2"
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: "Operating system/version"
-      placeholder: "emacs 23"
-    validations:
-      required: true
-
   - type: textarea
     attributes:
       label: 'Steps to reproduce using "nvim -u minimal_init.lua"'
@@ -65,14 +52,29 @@ body:
         _Note_: if the issue is with an autocompletion or other LSP plugin, report to that plugin's issue tracker.
     validations:
       required: true
-
   - type: textarea
     attributes:
       label: "Expected behavior"
       description: "Describe the behavior you expect. May include logs, images, or videos."
-  - type: textarea
+
+  - type: input
     attributes:
-      label: "Actual behavior"
+      label: "Neovim version (nvim -v)"
+      placeholder: "0.6.0 commit db1b0ee3b30f"
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: "Language server name/version"
+      placeholder: "rls 0.5.2"
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: "Operating system/version"
+      placeholder: "emacs 23"
+    validations:
+      required: true
 
   - type: input
     attributes:

README.md

@@ -75,7 +75,6 @@ See [`:help nvim-from-vim`](https://neovim.io/doc/user/nvim.html#nvim-from-vim)
 Project layout
 --------------
 
-    ├─ ci/              build automation
     ├─ cmake/           CMake utils
     ├─ cmake.config/    CMake defines
     ├─ cmake.deps/      subproject to fetch and build dependencies (optional)

runtime/doc/api.txt

@@ -1461,16 +1461,15 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                 "!" for |:map!|, or empty string for |:map|.
       • {lhs}   Left-hand-side |{lhs}| of the mapping.
       • {rhs}   Right-hand-side |{rhs}| of the mapping.
-      • {opts}  Optional parameters map: keys are |:map-arguments|, values are
+      • {opts}  Optional parameters map: Accepts all |:map-arguments| as keys
-                booleans (default false). Accepts all |:map-arguments| as keys
+                except |<buffer>|, values are booleans (default false). Also:
-                excluding |<buffer>| but including |:noremap| and "desc".
+                • "noremap" non-recursive mapping |:noremap|
-                Unknown key is an error. "desc" can be used to give a
+                • "desc" human-readable description.
-                description to the mapping. When called from Lua, also accepts
+                • "callback" Lua function called when the mapping is executed.
-                a "callback" key that takes a Lua function to call when the
+                • "replace_keycodes" (boolean) When "expr" is true, replace
-                mapping is executed. When "expr" is true, "replace_keycodes"
+                  keycodes in the resulting string (see
-                (boolean) can be used to replace keycodes in the resulting
+                  |nvim_replace_termcodes()|). Returning nil from the Lua
-                string (see |nvim_replace_termcodes()|), and a Lua callback
+                  "callback" is equivalent to returning an empty string.
-                returning `nil` is equivalent to returning an empty string.
 
 nvim_set_var({name}, {value})                                 *nvim_set_var()*
     Sets a global (g:) variable.
@@ -1678,7 +1677,7 @@ Command Functions                                                *api-command*
 
                                               *nvim_buf_create_user_command()*
 nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
-    Create a new user command |user-commands| in the given buffer.
+    Creates a buffer-local command |user-commands|.
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer.
@@ -1743,15 +1742,12 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
 
                                                   *nvim_create_user_command()*
 nvim_create_user_command({name}, {command}, {*opts})
-    Create a new user command |user-commands|
+    Creates a global |user-commands| command.
 
-    {name} is the name of the new command. The name must begin with an
+    For Lua usage see |lua-guide-commands-create|.
-    uppercase letter.
-
-    {command} is the replacement text or Lua function to execute.
 
     Example: >vim
-       :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
+       :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
        :SayHello
        Hello world!
 <
@@ -1783,19 +1779,20 @@ nvim_create_user_command({name}, {command}, {*opts})
                    • smods: (table) Command modifiers in a structured format.
                      Has the same structure as the "mods" key of
                      |nvim_parse_cmd()|.
-      • {opts}     Optional command attributes. See |command-attributes| for
+      • {opts}     Optional |command-attributes|.
-                   more details. To use boolean attributes (such as
+                   • Set boolean attributes such as |:command-bang| or
-                   |:command-bang| or |:command-bar|) set the value to "true".
+                     |:command-bar| to true (but not |:command-buffer|, use
-                   In addition to the string options listed in
+                     |nvim_buf_create_user_command()| instead).
-                   |:command-complete|, the "complete" key also accepts a Lua
+                   • "complete" |:command-complete| also accepts a Lua
-                   function which works like the "customlist" completion mode
+                     function which works like
-                   |:command-completion-customlist|. Additional parameters:
+                     |:command-completion-customlist|.
-                   • desc: (string) Used for listing the command when a Lua
+                   • Other parameters:
-                     function is used for {command}.
+                     • desc: (string) Used for listing the command when a Lua
-                   • force: (boolean, default true) Override any previous
+                       function is used for {command}.
-                     definition.
+                     • force: (boolean, default true) Override any previous
-                   • preview: (function) Preview callback for 'inccommand'
+                       definition.
-                     |:command-preview|
+                     • preview: (function) Preview callback for 'inccommand'
+                       |:command-preview|
 
 nvim_del_user_command({name})                        *nvim_del_user_command()*
     Delete a user-defined command.

runtime/doc/develop.txt

@@ -132,6 +132,18 @@ DOCUMENTATION						*dev-doc*
   optimize for the reader's time and energy: be "precise yet concise".
     - See https://developers.google.com/style/tone
     - Prefer the active voice: "Foo does X", not "X is done by Foo".
+- Start function docstrings with present tense ("Gets"), not imperative
+  ("Get"). This tends to reduce ambiguity and improve clarity. >
+    GOOD:
+    /// Gets a highlight definition.
+    BAD:
+    /// Get a highlight definition.
+- Avoid starting docstrings with "The" or "A" unless needed to avoid
+  ambiguity. This is a visual aid and reduces noise. >
+    GOOD:
+    /// @param dirname Path fragment before `pend`
+    BAD:
+    /// @param dirname The path fragment before `pend`
 - Vim differences:
     - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
       differences from Vim; no other distinction is necessary.
@@ -143,13 +155,6 @@ DOCUMENTATION						*dev-doc*
       not "the user host terminal".
     - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
       in prose if possible.
-- Docstrings: do not start parameter descriptions with "The" or "A" unless it
-  is critical to avoid ambiguity. >
-    GOOD:
-    /// @param dirname Path fragment before `pend`
-    BAD:
-    /// @param dirname The path fragment before `pend`
-<
 
 Documentation format ~
 
@@ -159,14 +164,14 @@ https://neovim.io/doc/user ).
 
 Strict "vimdoc" subset:
 
-- Use lists (like this!) prefixed with "-", "*", or "•", for adjacent lines
+- Use lists (like this!) prefixed with "-" or "•", for adjacent lines that you
-  that you don't want auto-wrapped. Lists are always rendered with "flow"
+  don't want to auto-wrap. Lists are always rendered with "flow" layout
-  (soft-wrapped) layout instead of preformatted (hard-wrapped) layout common
+  (soft-wrapped) instead of preformatted (hard-wrapped) layout common in
-  in legacy :help docs.
+  legacy :help docs.
   - Limitation: currently the parser https://github.com/neovim/tree-sitter-vimdoc
     does not understand numbered listitems, so use a bullet symbol (- or •)
-    before numbered items, e.g. "- 1." instead of "1.".
+    before numbered items, e.g. "• 1." instead of "1.".
-- Separate blocks (paragraphs) of content by a blank line(s).
+- Separate blocks (paragraphs) of content by a blank line.
 - Do not use indentation in random places—that prevents the page from using
   "flow" layout. If you need a preformatted section, put it in
   a |help-codeblock| starting with ">".
@@ -246,7 +251,9 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     ---@returns false if client should cancel the paste.
 
 
-LUA							*dev-lua*
+LUA STDLIB DESIGN GUIDELINES				*dev-lua*
+
+See also |dev-naming|.
 
 - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
   pseudo-OOP designs. Plugin authors just want functions to call, not a big,
@@ -255,10 +262,26 @@ LUA							*dev-lua*
   tables or values are easier to serialize, easier to construct from literals,
   easier to inspect and print, and inherently compatible with all Lua plugins.
   (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
+- stdlib functions should follow these common patterns:
+  - accept iterable instead of table
+    - exception: in some cases iterable doesn't make sense, e.g. spair() sorts
+      the input by definition, so there is no reason for it to accept an
+      iterable, because the input needs to be "hydrated", it can't operate on
+      a "stream".
+  - return iterable instead of table
+  - mimic the pairs() or ipairs() interface if the function is intended to be
+    used in a "for" loop.
 
 
-API							*dev-api*
+API DESIGN GUIDELINES					*dev-api*
 
+See also |dev-naming|.
+
+- When adding an API, check the following:
+  - What precedents did you draw from? How does your solution compare to them?
+  - Does your new API allow future expansion? How? Or why not?
+  - Is the new API similar to existing APIs? Do we need to deprecate the old ones?
+  - Did you cross-reference related concepts in the docs?
 - Avoid "mutually exclusive" parameters--via constraints or limitations, if
   necessary. For example nvim_create_autocmd() has mutually exclusive
   "callback" and "command" args; but the "command" arg could be eliminated by
@@ -266,66 +289,95 @@ API							*dev-api*
   "callback" arg as an Ex command (which can call Vimscript functions). The
   "buffer" arg could also be eliminated by treating a number "pattern" as
   a buffer number.
+- Avoid functions that depend on cursor position, current buffer, etc. Instead
+  the function should take a position parameter, buffer parameter, etc.
 
-                                                              *dev-api-naming*
+NAMING GUIDELINES                                       *dev-naming*
-Use this format to name new RPC |API| functions:
 
-    nvim_{thing}_{action}_{arbitrary-qualifiers}
+Naming is exceedingly important: the name of a thing is the primary interface
+for uses it, discusses it, searches for it, shares it... Consistent
+naming in the stdlib, API, and UI helps both users and developers discover and
+intuitively understand related concepts ("families"), and reduces cognitive
+burden. Discoverability encourages code re-use and likewise avoids redundant,
+overlapping mechanisms, which reduces code surface-area, and thereby minimizes
+bugs...
 
-If the function acts on an object then {thing} is the name of that object
+Naming conventions ~
-(e.g. "buf" or "win"). If the function operates in a "global" context then
-{thing} is usually omitted (but consider "namespacing" your global operations
-with a {thing} that groups functions under a common concept).
 
-Use existing common {action} names if possible:
+In general, look for precedent when choosing a name, that is, look at existing
-    - add       Append to, or insert into, a collection
+(non-deprecated) functions. In particular, see below...
-    - call      Call a function
+
-    - create    Create a new (non-trivial) thing
+							*dev-name-common*
-    - del       Delete a thing (or group of things)
+Use existing common {verb} names (actions) if possible:
-    - eval      Evaluate an expression
+    - add:          Appends or inserts into a collection
-    - exec      Execute code
+    - attach:       Listens to something to get events from it (TODO: rename to "on"?)
-    - fmt       Format
+    - call:         Calls a function
-    - get       Get things (often by a query)
+    - clear:        Clears state but does not destroy the container
-    - open      Open
+    - create:       Creates a new (non-trivial) thing (TODO: rename to "def"?)
-    - parse     Parse something into a structured form
+    - del:          Deletes a thing (or group of things)
-    - set       Set a thing (or group of things)
+    - detach:       Dispose attached listener (TODO: rename to "un"?)
+    - eval:         Evaluates an expression
+    - exec:         Executes code
+    - fmt:          Formats
+    - get:          Gets things (often by a query)
+    - inspect:      Presents a high-level, often interactive, view
+    - open:         Opens something (a buffer, window, …)
+    - parse:        Parses something into a structured form
+    - set:          Sets a thing (or group of things)
+    - try_{verb}:   Best-effort operation, failure returns null or error obj
 
 Do NOT use these deprecated verbs:
-    - list      Redundant with "get"
+    - list:         Redundant with "get"
+    - show:         Redundant with "print", "echo"
+    - notify:       Redundant with "print", "echo"
 
-Use consistent names for {thing} (nouns) in API functions: buffer is called
+Use consistent names for {noun} (nouns) in API functions: buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.
-    - buf       Buffer
+    - buf:          Buffer
-    - chan      |channel|
+    - chan:         |channel|
-    - cmd       Command
+    - cmd:          Command
-    - cmdline   Command-line UI or input
+    - cmdline:      Command-line UI or input
-    - fn        Function
+    - fn:           Function
-    - hl        Highlight
+    - hl:           Highlight
-    - pos       Position
+    - pos:          Position
-    - proc      System process
+    - proc:         System process
-    - tabpage   Tabpage
+    - tabpage:      Tabpage
-    - win       Window
+    - win:          Window
 
 Do NOT use these deprecated nouns:
     - buffer
     - command
     - window
 
-Example:
+							*dev-name-events*
-    `nvim_get_keymap('v')` operates in a global context (first parameter is not
+Use the "on_" prefix to name event-handling callbacks and also the interface for
-    a Buffer). The "get" {action} indicates that it gets anything matching the
+"registering" such handlers (on_key). The dual nature is acceptable to avoid
-    given filter parameter. There is no need for a "list" action because
+a confused collection of naming conventions for these related concepts.
-    `nvim_get_keymap('')` (i.e., empty filter) returns all items.
 
-Example:
+Editor |events| (autocommands) are historically named like: >
-    `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
+    {Noun}{Event}
-    and uses the "del" {action}.
 
-Use this format to name new API events:
+Use this format to name API (RPC) events: >
-    nvim_{thing}_{event}_event
+    nvim_{noun}_{event-name}_event
 
-Example:
+Example: >
-    `nvim_buf_changedtick_event`
+    nvim_buf_changedtick_event
+<
+							*dev-name-api*
+Use this format to name new RPC |API| functions: >
+    nvim_{noun}_{verb}_{arbitrary-qualifiers}
+
+If the function acts on an object then {noun} is the name of that object
+(e.g. "buf" or "win"). If the function operates in a "global" context then
+{noun} is usually omitted (but consider "namespacing" your global operations
+with a {noun} that groups functions under a common concept).
+
+- Example: `nvim_get_keymap('v')` operates in a global context (first
+  parameter is not a Buffer). The "get" verb indicates that it gets anything
+  matching the given filter parameter. A "list" verb is unnecessary because
+  `nvim_get_keymap('')` (empty filter) returns all items.
+- Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
+  and uses the "del" {verb}.
 
 
 API-CLIENT						*dev-api-client*
@@ -417,19 +469,4 @@ External UIs are expected to implement these common features:
   published in this event. See also "mouse_on", "mouse_off".
 
 
-NAMING							*dev-naming*
-
-Naming is important. Consistent naming in the API and UI helps both users and
-developers discover and intuitively understand related concepts ("families"),
-and reduces cognitive burden. Discoverability encourages code re-use and
-likewise avoids redundant, overlapping mechanisms, which reduces code
-surface-area, and thereby minimizes bugs...
-
-Naming conventions ~
-
-Use the "on_" prefix to name event handlers and also the interface for
-"registering" such handlers (on_key). The dual nature is acceptable to avoid
-a confused collection of naming conventions for these related concepts.
-
-
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:

runtime/doc/editing.txt

@@ -1668,29 +1668,26 @@ There are three different types of searching:
 ==============================================================================
 12. Trusted Files						*trust*
 
-Nvim has the ability to execute arbitrary code through the 'exrc' option. In
+Nvim executes arbitrary code found on the filesystem if 'exrc' is enabled. To
-order to prevent executing code from untrusted sources, Nvim has the concept of
+prevent executing malicious code, only "trusted files" are executed. You can
-"trusted files". An untrusted file will not be executed without the user's
+mark a file as trusted or untrusted using the |:trust| command or the
-consent, and a user can permanently mark a file as trusted or untrusted using
+|vim.secure.read()| function.
-the |:trust| command or the |vim.secure.read()| function.
 
 							*:trust* *E5570*
-:trust [++deny] [++remove] [{file}]
+:trust [++deny] [++remove] [file]
 
-			Manage files in the trust database. Without any options
+			Manage trusted files. Without ++ options, :trust marks
-			or arguments, :trust adds the file associated with the
+			[file] (or current buffer if no [file]) as trusted,
-			current buffer to the trust database, along with the
+			keyed on a hash of its contents. The trust list is
-			SHA256 hash of its contents.
+			stored on disk, Nvim will re-use it after restarting.
 
-			[++deny] marks the file associated with the current
+			[++deny] marks [file] (or current buffer if no [file]) as
-			buffer (or {file}, if given) as denied; no prompts will
+			untrusted: it will never be executed, 'exrc' will
-			be displayed to the user and the file will never be
+			ignore it.
-			executed.
 
-			[++remove] removes the file associated with the current
+			[++remove] removes [file] (or current buffer if no
-			buffer (or {file}, if given) from the trust database.
+			[file]) from the trust list. When the file is
-			Future attempts to read the file in a secure setting
+			discovered by 'exrc' or |vim.secure.read()|, the user
-			(i.e. with 'exrc' or |vim.secure.read()|) will prompt
+			will be asked whether to trust or deny the file.
-			the user if the file is trusted.
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/editorconfig.txt

@@ -6,25 +6,21 @@
 
 EditorConfig integration                                        *editorconfig*
 
-Nvim natively supports EditorConfig. When a file is opened, Nvim searches
+Nvim supports EditorConfig. When a file is opened, Nvim searches all parent
-upward through all of the parent directories of that file looking for
+directories of that file for ".editorconfig" files, parses them, and applies
-".editorconfig" files. Each of these is parsed and any properties that match
+any properties that match the opened file. Think of it like 'modeline' for an
-the opened file are applied.
+entire (recursive) directory. For more information see
-
+https://editorconfig.org/.
-For more information on EditorConfig, see https://editorconfig.org/.
 
                                                *g:editorconfig* *b:editorconfig*
-EditorConfig integration can be disabled globally by adding >lua
+EditorConfig is enabled by default. To disable it, add to your config: >lua
 
     vim.g.editorconfig = false
 <
-to the user's |init.lua| file (or the Vimscript equivalent to |init.vim|). It
+(Vimscript: `let g:editorconfig = v:false`). It can also be disabled
-can also be disabled per-buffer by setting the |b:editorconfig| buffer-local
+per-buffer by setting the |b:editorconfig| buffer-local variable to `false`.
-variable to `false`.
 
-When Nvim finds a valid .editorconfig file it will store the applied
+Nvim stores the applied properties in |b:editorconfig| if it is not `false`.
-properties in the buffer variable |b:editorconfig| if it was not already set to
-`false` by the user.
 
                                                      *editorconfig-properties*
 The following properties are supported by default:
@@ -88,4 +84,4 @@ Example: >lua
       vim.b[bufnr].foo = val
     end
 <
- vim:tw=78:ts=8:noet:ft=help:norl:
+ vim:tw=78:ts=8:et:sw=4:ft=help:norl:

runtime/doc/lua-guide.txt

@@ -657,7 +657,7 @@ See also
 • |nvim_exec_autocmds()|: execute all matching autocommands
 
 ==============================================================================
-User commands                                           *lua-guide-usercommands*
+User commands                                           *lua-guide-commands*
 
 |user-commands| are custom Vim commands that call a Vimscript or Lua function.
 Just like built-in commands, they can have arguments, act on ranges, or have
@@ -665,7 +665,7 @@ custom completion of arguments. As these are most useful for plugins, we will
 cover only the basics of this advanced topic.
 
 ------------------------------------------------------------------------------
-Creating user commands                           *lua-guide-usercommands-create*
+Creating user commands                           *lua-guide-commands-create*
 
 User commands can be created through the Neovim API with
 `vim.api.`|nvim_create_user_command()|. This function takes three mandatory
@@ -734,7 +734,7 @@ the remaining arguments are the same as for |nvim_create_user_command()|:
       { nargs = 1 })
 <
 ------------------------------------------------------------------------------
-Deleting user commands                           *lua-guide-usercommands-delete*
+Deleting user commands                           *lua-guide-commands-delete*
 
 User commands can be deleted with `vim.api.`|nvim_del_user_command()|. The only
 argument is the name of the command:

runtime/doc/lua.txt

@@ -2029,7 +2029,8 @@ uri_to_fname({uri})                                       *vim.uri_to_fname()*
 Lua module: ui                                                        *lua-ui*
 
 input({opts}, {on_confirm})                                   *vim.ui.input()*
-    Prompts the user for input
+    Prompts the user for input, allowing arbitrary (potentially asynchronous)
+    work until `on_confirm`.
 
     Example: >lua
 
@@ -2054,7 +2055,8 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
                       entered), or `nil` if the user aborted the dialog.
 
 select({items}, {opts}, {on_choice})                         *vim.ui.select()*
-    Prompts the user to pick a single item from a collection of entries
+    Prompts the user to pick from a list of items, allowing arbitrary
+    (potentially asynchronous) work until `on_choice`.
 
     Example: >lua
 
@@ -2253,57 +2255,38 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
         |vim.keymap.set()|
 
 set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
-    Add a new |mapping|. Examples: >lua
+    Adds a new |mapping|. Examples: >lua
 
-       -- Can add mapping to Lua functions
+       -- Map to a Lua function:
        vim.keymap.set('n', 'lhs', function() print("real lua function") end)
-
+       -- Map to multiple modes:
-       -- Can use it to map multiple modes
        vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
-
+       -- Buffer-local mapping:
-       -- Can add mapping for specific buffer
        vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
-
+       -- Expr mapping:
-       -- Expr mappings
        vim.keymap.set('i', '<Tab>', function()
          return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
        end, { expr = true })
-       -- <Plug> mappings
+       -- <Plug> mapping:
        vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
 <
 
-    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: >lua
-
-        vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
-<
-
     Parameters: ~
-      • {mode}  string|table Same mode short names as |nvim_set_keymap()|. Can
+      • {mode}  string|table Mode short-name, see |nvim_set_keymap()|. Can
                 also be list of modes to create mapping on multiple modes.
       • {lhs}   (string) Left-hand side |{lhs}| of the mapping.
-      • {rhs}   string|function Right-hand side |{rhs}| of the mapping. Can
+      • {rhs}   string|function Right-hand side |{rhs}| of the mapping, can be
-                also be a Lua function.
+                a Lua function.
-      • {opts}  (table|nil) A table of |:map-arguments|.
+      • {opts}  (table|nil) Table of |:map-arguments|.
-                • Accepts options accepted by the {opts} parameter in
+                • Same as |nvim_set_keymap()| {opts}, except:
-                  |nvim_set_keymap()|, with the following notable differences:
+                  • "replace_keycodes" defaults to `true` if "expr" is `true`.
-                  • replace_keycodes: Defaults to `true` if "expr" is `true`.
+                  • "noremap": inverse of "remap" (see below).
-                  • noremap: Always overridden with the inverse of "remap"
-                    (see below).
 
-                • In addition to those options, the table accepts the
+                • Also accepts:
-                  following keys:
+                  • "buffer" number|boolean Creates buffer-local mapping, `0`
-                  • buffer: (number or boolean) Add a mapping to the given
+                    or `true` for current buffer.
-                    buffer. When `0` or `true`, use the current buffer.
+                  • remap: (boolean) Make the mapping recursive. Inverses
-                  • remap: (boolean) Make the mapping recursive. This is the
+                    "noremap". Defaults to `false`.
-                    inverse of the "noremap" option from |nvim_set_keymap()|.
-                    Defaults to `false`.
 
     See also: ~
         |nvim_set_keymap()|

runtime/doc/options.txt

@@ -401,20 +401,15 @@ the system, mostly it is something like 256 or 1024 characters.
 ==============================================================================
 2. Automatically setting options			*auto-setting*
 
-Besides changing options with the ":set" command, there are three alternatives
+Besides changing options with the ":set" command, you can set options
-to set options automatically for one or more files:
+automatically in various ways:
 
-1. When starting Vim initializations are read from various places.  See
+1. With a |config| file or a |startup| argument. You can create an
-   |initialization|.  Most of them are performed for all editing sessions,
+   initialization file with |:mkvimrc|, |:mkview| and |:mksession|.
-   and some of them depend on the directory where Vim is started.
+2. |autocommand|s executed when you edit a file.
-   You can create an initialization file with |:mkvimrc|, |:mkview| and
+3. ".nvim.lua" files in the current directory, if 'exrc' is enabled.
-   |:mksession|.
+4. |editorconfig| in the current buffer's directory or ancestors.
-2. If you start editing a new file, the automatic commands are executed.
+5. 'modeline' settings found at the beginning or end of the file. See below.
-   This can be used to set options for files matching a particular pattern and
-   many other things.  See |autocommand|.
-3. If you start editing a new file, and the 'modeline' option is on, a
-   number of lines at the beginning and end of the file are checked for
-   modelines.  This is explained here.
 
 					*modeline* *vim:* *vi:* *ex:* *E520*
 There are two forms of modelines.  The first form:
@@ -2267,15 +2262,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 					*'exrc'* *'ex'* *'noexrc'* *'noex'*
 'exrc' 'ex'		boolean (default off)
 			global
-	Enables the reading of .nvim.lua, .nvimrc, and .exrc files in the current
+	Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
-	directory.
+	current directory, if the file is in the |trust| list. Use |:trust| to
+	manage trusted files. See also |vim.secure.read()|.
 
-	The file is only sourced if the user indicates the file is trusted. If
+	Compare 'exrc' to |editorconfig|:
-	it is, the SHA256 hash of the file contents and the full path of the
+	- 'exrc' can execute any code; editorconfig only specifies settings.
-	file are persisted to a trust database. The user is only prompted
+	- 'exrc' is Nvim-specific; editorconfig works in other editors.
-	again if the file contents change. See |vim.secure.read()|.
-
-	Use |:trust| to manage the trusted file database.
 
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.

runtime/doc/support.txt

@@ -14,12 +14,16 @@ Supported platforms					 *supported-platforms*
 `System`          `Tier`      `Versions`                  `Tested versions`
 Linux            1      >= 2.6.32, glibc >= 2.12     Ubuntu 22.04
 macOS (Intel)    1      >= 10.15                     macOS 12
-Windows 64-bit   1      >= 8                         Windows Server 2019
+Windows 64-bit   1      >= 8 (see note below)        Windows Server 2019
 FreeBSD          1      >= 10                        FreeBSD 13
 macOS (M1)       2      >= 10.15
 OpenBSD          2      >= 7
 MinGW            2      MinGW-w64
 
+Note: Windows 10 "Version 1809" or later is required for |:terminal|. To check
+your Windows version, run the "winver" command and look for "Version xxxx"
+(NOT "OS Build").
+
 Support types ~
 
 * Tier 1: Officially supported and tested with CI. Any contributed patch

runtime/doc/ui.txt

@@ -809,5 +809,8 @@ events, which the UI must handle.
 	Sent when |:messages| command is invoked. History is sent as a list of
 	entries, where each entry is a `[kind, content]` tuple.
 
+["msg_history_clear"] ~
+	Clear the |:messages| history.
+
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/vim_diff.txt

@@ -72,6 +72,7 @@ Defaults					            *nvim-defaults*
 - 'wildmenu' is enabled
 - 'wildoptions' defaults to "pum,tagfile"
 
+- |editorconfig| plugin is enabled, .editorconfig settings are applied.
 - |man.lua| plugin is enabled, so |:Man| is available by default.
 - |matchit| plugin is enabled. To disable it in your config: >vim
     :let loaded_matchit = 1

runtime/lua/vim/keymap.lua

@@ -1,51 +1,35 @@
 local keymap = {}
 
---- Add a new |mapping|.
+--- Adds a new |mapping|.
 --- Examples:
 --- <pre>lua
----   -- Can add mapping to Lua functions
+---   -- Map to a Lua function:
 ---   vim.keymap.set('n', 'lhs', function() print("real lua function") end)
----
+---   -- Map to multiple modes:
----   -- Can use it to map multiple modes
 ---   vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
----
+---   -- Buffer-local mapping:
----   -- Can add mapping for specific buffer
 ---   vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
----
+---   -- Expr mapping:
----   -- Expr mappings
 ---   vim.keymap.set('i', '<Tab>', function()
 ---     return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
 ---   end, { expr = true })
----   -- <Plug> mappings
+---   -- <Plug> mapping:
 ---   vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
 --- </pre>
 ---
---- Note that in a mapping like:
+---@param mode string|table    Mode short-name, see |nvim_set_keymap()|.
---- <pre>lua
----    vim.keymap.set('n', 'asdf', require('jkl').my_fun)
---- </pre>
----
---- 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:
---- <pre>lua
----    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
---- </pre>
----
----@param mode string|table    Same mode short names as |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
 ---@param lhs string           Left-hand side |{lhs}| of the mapping.
----@param rhs string|function  Right-hand side |{rhs}| of the mapping. Can also be a Lua function.
+---@param rhs string|function  Right-hand side |{rhs}| of the mapping, can be a Lua function.
---
+---
----@param opts table|nil A table of |:map-arguments|.
+---@param opts table|nil Table of |:map-arguments|.
----                      + Accepts options accepted by the {opts} parameter in |nvim_set_keymap()|,
+---                      - Same as |nvim_set_keymap()| {opts}, except:
----                        with the following notable differences:
+---                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
----                        - replace_keycodes: Defaults to `true` if "expr" is `true`.
+---                        - "noremap": inverse of "remap" (see below).
----                        - noremap: Always overridden with the inverse of "remap" (see below).
+---                      - Also accepts:
----                      + In addition to those options, the table accepts the following keys:
+---                        - "buffer" number|boolean Creates buffer-local mapping, `0` or `true`
----                        - buffer: (number or boolean) Add a mapping to the given buffer.
+---                        for current buffer.
----                        When `0` or `true`, use the current buffer.
+---                        - remap: (boolean) Make the mapping recursive. Inverses "noremap".
----                        - remap: (boolean) Make the mapping recursive.
----                        This is the inverse of the "noremap" option from |nvim_set_keymap()|.
 ---                        Defaults to `false`.
 ---@see |nvim_set_keymap()|
 function keymap.set(mode, lhs, rhs, opts)

runtime/lua/vim/ui.lua

@@ -1,6 +1,7 @@
 local M = {}
 
---- Prompts the user to pick a single item from a collection of entries
+--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
+--- work until `on_choice`.
 ---
 ---@param items table Arbitrary items
 ---@param opts table Additional options
@@ -35,7 +36,6 @@ local M = {}
 ---     end
 --- end)
 --- </pre>
-
 function M.select(items, opts, on_choice)
   vim.validate({
     items = { items, 'table', false },
@@ -55,7 +55,8 @@ function M.select(items, opts, on_choice)
   end
 end
 
---- Prompts the user for input
+--- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
+--- `on_confirm`.
 ---
 ---@param opts table Additional options. See |input()|
 ---     - prompt (string|nil)

src/nvim/README.md

@@ -81,6 +81,13 @@ Logs will be written to `${HOME}/logs/*san.PID` then.
 
 For more information: https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
 
+Reproducible build
+------------------
+
+To make a reproducible build of Nvim, set cmake variable `LUA_GEN_PRG` to
+a LuaJIT binary built with `LUAJIT_SECURITY_PRN=0`. See commit
+cb757f2663e6950e655c6306d713338dfa66b18d.
+
 Debug: Performance
 ------------------
 

src/nvim/api/command.c

@@ -899,15 +899,13 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
   }
 }
 
-/// Create a new user command |user-commands|
+/// Creates a global |user-commands| command.
 ///
-/// {name} is the name of the new command. The name must begin with an uppercase letter.
+/// For Lua usage see |lua-guide-commands-create|.
-///
-/// {command} is the replacement text or Lua function to execute.
 ///
 /// Example:
 /// <pre>vim
-///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
+///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
 ///    :SayHello
 ///    Hello world!
 /// </pre>
@@ -929,15 +927,16 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
 ///                 - mods: (string) Command modifiers, if any |<mods>|
 ///                 - smods: (table) Command modifiers in a structured format. Has the same
 ///                 structure as the "mods" key of |nvim_parse_cmd()|.
-/// @param  opts    Optional command attributes. See |command-attributes| for more details. To use
+/// @param  opts    Optional |command-attributes|.
-///                 boolean attributes (such as |:command-bang| or |:command-bar|) set the value to
+///                 - Set boolean attributes such as |:command-bang| or |:command-bar| to true (but
-///                 "true". In addition to the string options listed in |:command-complete|, the
+///                   not |:command-buffer|, use |nvim_buf_create_user_command()| instead).
-///                 "complete" key also accepts a Lua function which works like the "customlist"
+///                 - "complete" |:command-complete| also accepts a Lua function which works like
-///                 completion mode |:command-completion-customlist|. Additional parameters:
+///                   |:command-completion-customlist|.
-///                 - desc: (string) Used for listing the command when a Lua function is used for
+///                 - Other parameters:
-///                                  {command}.
+///                   - desc: (string) Used for listing the command when a Lua function is used for
-///                 - force: (boolean, default true) Override any previous definition.
+///                                    {command}.
-///                 - preview: (function) Preview callback for 'inccommand' |:command-preview|
+///                   - force: (boolean, default true) Override any previous definition.
+///                   - preview: (function) Preview callback for 'inccommand' |:command-preview|
 /// @param[out] err Error details, if any.
 void nvim_create_user_command(String name, Object command, Dict(user_command) *opts, Error *err)
   FUNC_API_SINCE(9)
@@ -955,7 +954,7 @@ void nvim_del_user_command(String name, Error *err)
   nvim_buf_del_user_command(-1, name, err);
 }
 
-/// Create a new user command |user-commands| in the given buffer.
+/// Creates a buffer-local command |user-commands|.
 ///
 /// @param  buffer  Buffer handle, or 0 for current buffer.
 /// @param[out] err Error details, if any.

src/nvim/api/vim.c

@@ -1442,15 +1442,14 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 ///               or "!" for |:map!|, or empty string for |:map|.
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
-/// @param  opts  Optional parameters map: keys are |:map-arguments|, values are booleans (default
+/// @param  opts  Optional parameters map: Accepts all |:map-arguments| as keys except |<buffer>|,
-///               false). Accepts all |:map-arguments| as keys excluding |<buffer>| but including
+///               values are booleans (default false). Also:
-///               |:noremap| and "desc". Unknown key is an error.
+///               - "noremap" non-recursive mapping |:noremap|
-///               "desc" can be used to give a description to the mapping.
+///               - "desc" human-readable description.
-///               When called from Lua, also accepts a "callback" key that takes a Lua function to
+///               - "callback" Lua function called when the mapping is executed.
-///               call when the mapping is executed.
+///               - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
-///               When "expr" is true, "replace_keycodes" (boolean) can be used to replace keycodes
+///                 resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua
-///               in the resulting string (see |nvim_replace_termcodes()|), and a Lua callback
+///                 "callback" is equivalent to returning an empty string.
-///               returning `nil` is equivalent to returning an empty string.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(uint64_t channel_id, String mode, String lhs, String rhs, Dict(keymap) *opts,
                      Error *err)