docs: misc #32959

src/gen/gen_api_dispatch.lua

@@ -1,3 +1,5 @@
+-- Generates C code to bridge API <=> Lua.
+--
 -- Example (manual) invocation:
 --
 --    make
@@ -192,7 +194,7 @@ for _, f in ipairs(shallowcopy(functions)) do
           .. ' has deprecated alias\n'
           .. newname
           .. ' which has a separate implementation.\n'
-          .. 'Please remove it from src/nvim/api/dispatch_deprecated.lua'
+          .. 'Remove it from src/nvim/api/dispatch_deprecated.lua'
       )
       os.exit(1)
     end
@@ -729,6 +731,10 @@ output:write('\n')
 
 local lua_c_functions = {}
 
+--- Generates C code to bridge RPC API <=> Lua.
+---
+--- Inspect the result here:
+---    build/src/nvim/auto/api/private/dispatch_wrappers.generated.h
 local function process_function(fn)
   local lua_c_function_name = ('nlua_api_%s'):format(fn.name)
   write_shifted_output(

src/nvim/api/autocmd.c

@@ -53,14 +53,14 @@ static int64_t next_autocmd_id = 1;
 /// ```lua
 /// -- Matches all criteria
 /// autocommands = vim.api.nvim_get_autocmds({
-///   group = "MyGroup",
-///   event = {"BufEnter", "BufWinEnter"},
-///   pattern = {"*.c", "*.h"}
+///   group = 'MyGroup',
+///   event = {'BufEnter', 'BufWinEnter'},
+///   pattern = {'*.c', '*.h'}
 /// })
 ///
 /// -- All commands from one group
 /// autocommands = vim.api.nvim_get_autocmds({
-///   group = "MyGroup",
+///   group = 'MyGroup',
 /// })
 /// ```
 ///
@@ -336,8 +336,8 @@ cleanup:
 /// Example using Lua callback:
 ///
 /// ```lua
-/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///   pattern = {"*.c", "*.h"},
+/// vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+///   pattern = {'*.c', '*.h'},
 ///   callback = function(ev)
 ///     print(string.format('event fired: %s', vim.inspect(ev)))
 ///   end
@@ -347,8 +347,8 @@ cleanup:
 /// Example using an Ex command as the handler:
 ///
 /// ```lua
-/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///   pattern = {"*.c", "*.h"},
+/// vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+///   pattern = {'*.c', '*.h'},
 ///   command = "echo 'Entering a C or C++ file'",
 /// })
 /// ```
@@ -357,7 +357,7 @@ cleanup:
 /// and "~" must be expanded explicitly:
 ///
 /// ```lua
-/// pattern = vim.fn.expand("~") .. "/some/path/*.py"
+/// pattern = vim.fn.expand('~') .. '/some/path/*.py'
 /// ```
 ///
 /// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
@@ -603,7 +603,7 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err)
 /// To get an existing group id, do:
 ///
 /// ```lua
-/// local id = vim.api.nvim_create_augroup("MyGroup", {
+/// local id = vim.api.nvim_create_augroup('my.lsp.config', {
 ///     clear = false
 /// })
 /// ```

src/nvim/channel.c

@@ -514,8 +514,7 @@ void channel_from_connection(SocketWatcher *watcher)
   channel_create_event(channel, watcher->addr);
 }
 
-/// Creates an API channel from stdin/stdout. This is used when embedding
-/// Neovim
+/// Creates an API channel from stdin/stdout. Used when embedding Nvim.
 uint64_t channel_from_stdio(bool rpc, CallbackReader on_output, const char **error)
   FUNC_ATTR_NONNULL_ALL
 {

src/nvim/eval/funcs.c

@@ -3834,6 +3834,7 @@ static const char *pty_ignored_env_vars[] = {
   "COLORFGBG",
   "COLORTERM",
 #endif
+  // Nvim-owned env vars. #6764
   "VIM",
   "VIMRUNTIME",
   NULL
@@ -3870,9 +3871,8 @@ dict_T *create_environment(const dictitem_T *job_env, const bool clear_env, cons
     tv_dict_free(temp_env.vval.v_dict);
 
     if (pty) {
-      // These environment variables generally shouldn't be propagated to the
-      // child process.  We're removing them here so the user can still decide
-      // they want to explicitly set them.
+      // These env vars shouldn't propagate to the child process. #6764
+      // Remove them here, then the user may decide to explicitly set them below.
       for (size_t i = 0;
            i < ARRAY_SIZE(pty_ignored_env_vars) && pty_ignored_env_vars[i];
            i++) {

src/nvim/main.c

@@ -165,7 +165,7 @@ void event_init(void)
 }
 
 /// @returns false if main_loop could not be closed gracefully
-bool event_teardown(void)
+static bool event_teardown(void)
 {
   if (!main_loop.events) {
     input_stop();

src/nvim/vvars.lua

@@ -674,8 +674,9 @@ M.vars = {
       Read-only.
 
                                                            *$NVIM*
-      $NVIM is set by |terminal| and |jobstart()|, and is thus
-      a hint that the current environment is a subprocess of Nvim.
+      $NVIM is set to v:servername by |terminal| and |jobstart()|,
+      and is thus a hint that the current environment is a child
+      (direct subprocess) of Nvim.
 
       Example: a child Nvim process can detect and make requests to
       its parent Nvim: >lua