doc: minor comment tweaks

runtime/doc/deprecated.txt

@@ -30,7 +30,7 @@ Highlight groups ~
 Functions ~
 *buffer_exists()*	Obsolete name for |bufexists()|.
 *buffer_name()*		Obsolete name for |bufname()|.
-*buffer_number()*	Obsolete name for |buffer_number()|.
+*buffer_number()*	Obsolete name for |bufnr()|.
 *file_readable()*	Obsolete name for |filereadable()|.
 *highlight_exists()*	Obsolete name for |hlexists()|.
 *highlightID()*		Obsolete name for |hlID()|.

src/nvim/diff.c

@@ -906,8 +906,7 @@ void ex_diffpatch(exarg_T *eap)
     eval_patch((char *) tmp_orig, (char *) eap->arg, (char *) tmp_new);
 #endif  // ifdef UNIX
   } else {
-    // Build the patch command and execute it. Ignore errors. Switch to
+    // Build the patch command and execute it. Ignore errors.
-    // cooked mode to allow the user to respond to prompts.
 #ifdef UNIX
     vim_snprintf((char *)buf, buflen, "patch -o %s %s < \"%s\"",
                  tmp_new, tmp_orig, fullname != NULL ? fullname : eap->arg);
@@ -915,8 +914,7 @@ void ex_diffpatch(exarg_T *eap)
     vim_snprintf((char *)buf, buflen, "patch -o %s %s < \"%s\"",
                  tmp_new, tmp_orig, eap->arg);
 #endif  // ifdef UNIX
-    // Avoid ShellCmdPost stuff
+    block_autocmds();  // Avoid ShellCmdPost stuff
-    block_autocmds();
     (void)call_shell(buf, kShellOptFilter, NULL);
     unblock_autocmds();
   }

src/nvim/event/queue.c

@@ -8,7 +8,7 @@
 // - removing a node from a child queue will remove the corresponding link node
 //   in the parent queue
 //
-// These properties allow neovim to organize and process events from different
+// These properties allow Nvim to organize and process events from different
 // sources with a certain degree of control. Here's how the queue is used:
 //
 //                         +----------------+
@@ -26,20 +26,20 @@
 //    +-----------+   +-----------+    +---------+    +---------+
 //
 //
-// In the above diagram, the lower boxes represents event emitters, each with
+// The lower boxes represents event emitters, each with its own private queue
-// it's own private queue that have the event loop queue as the parent.
+// having the event loop queue as the parent.
 //
 // When idle, the main loop spins the event loop which queues events from many
-// sources(channels, jobs, user...). Each event emitter pushes events to its own
+// sources (channels, jobs, user...). Each event emitter pushes events to its
 // private queue which is propagated to the event loop queue. When the main loop
 // consumes an event, the corresponding event is removed from the emitter's
 // queue.
 //
 // The main reason for this queue hierarchy is to allow focusing on a single
 // event emitter while blocking the main loop. For example, if the `jobwait`
-// vimscript function is called on job1, the main loop will temporarily stop
+// VimL function is called on job1, the main loop will temporarily stop polling
-// polling the event loop queue and poll job1 queue instead. Same with channels,
+// the event loop queue and poll job1 queue instead. Same with channels, when
-// when calling `rpcrequest`, we want to temporarily stop processing events from
+// calling `rpcrequest` we want to temporarily stop processing events from
 // other sources and focus on a specific channel.
 
 #include <assert.h>

src/nvim/ex_cmds.c

@@ -1154,15 +1154,11 @@ static void do_filter(
   }
   read_linecount = curbuf->b_ml.ml_line_count;
 
-  /*
+  // When call_shell() fails wait_return() is called to give the user a chance
-   * When call_shell() fails wait_return() is called to give the user a
+  // to read the error messages. Otherwise errors are ignored, so you can see
-   * chance to read the error messages. Otherwise errors are ignored, so you
+  // the error messages from the command that appear on stdout; use 'u' to fix
-   * can see the error messages from the command that appear on stdout; use
+  // the text.
-   * 'u' to fix the text
+  // Pass on the kShellDoOut flag when the output is being redirected.
-   * Switch to cooked mode when not redirecting stdin, avoids that something
-   * like ":r !cat" hangs.
-   * Pass on the kShellDoOut flag when the output is being redirected.
-   */
   if (call_shell(
         cmd_buf,
         kShellOptFilter | shell_flags,

src/nvim/globals.h

@@ -927,9 +927,9 @@ EXTERN FILE     *scriptin[NSCRIPT];         /* streams to read script from */
 EXTERN int curscript INIT(= 0);             /* index in scriptin[] */
 EXTERN FILE     *scriptout INIT(= NULL);    /* stream to write script to */
 
-/* volatile because it is used in signal handler catch_sigint(). */
+// volatile because it is used in a signal handler.
-EXTERN volatile int got_int INIT(= FALSE);    /* set to TRUE when interrupt
+EXTERN volatile int got_int INIT(= false);  // set to true when interrupt
-                                                 signal occurred */
+                                            // signal occurred
 EXTERN int bangredo INIT(= FALSE);          /* set to TRUE with ! command */
 EXTERN int searchcmdlen;                    /* length of previous search cmd */
 EXTERN int reg_do_extmatch INIT(= 0);       /* Used when compiling regexp:

src/nvim/os/shell.c

@@ -162,7 +162,7 @@ int os_call_shell(char_u *cmd, ShellOpts opts, char_u *extra_args)
 /// @param input The input to the shell (NULL for no input), passed to the
 ///              stdin of the resulting process.
 /// @param len The length of the input buffer (not used if `input` == NULL)
-/// @param[out] output A pointer to to a location where the output will be
+/// @param[out] output Pointer to a location where the output will be
 ///                    allocated and stored. Will point to NULL if the shell
 ///                    command did not output anything. If NULL is passed,
 ///                    the shell output will be ignored.
@@ -227,7 +227,7 @@ static int do_os_system(char **argv,
 
   // We want to deal with stream events as fast a possible while queueing
   // process events, so reset everything to NULL. It prevents closing the
-  // streams while there's still data in the OS buffer(due to the process
+  // streams while there's still data in the OS buffer (due to the process
   // exiting before all data is read).
   if (input != NULL) {
     proc->in->events = NULL;

src/nvim/rbuffer.h

@@ -1,4 +1,4 @@
-// Ring buffer implementation. This is basically an array that wraps read/write
+// Specialized ring buffer. This is basically an array that wraps read/write
 // pointers around the memory region. It should be more efficient than the old
 // RBuffer which required memmove() calls to relocate read/write positions.
 //

src/nvim/tui/tui.c

@@ -1,3 +1,5 @@
+// Terminal UI functions. Invoked (by ui_bridge.c) on the TUI thread.
+
 #include <assert.h>
 #include <stdbool.h>
 #include <stdio.h>

src/nvim/ui_bridge.c

@@ -1,5 +1,5 @@
-// FIXME(tarruda): This module is very repetitive. It might be a good idea to
+// UI wrapper for the built-in TUI. Sends UI requests to the TUI thread.
-// automatically generate it with a lua script during build
+
 #include <assert.h>
 #include <stdbool.h>
 #include <stdio.h>

src/nvim/ui_bridge.h

@@ -11,7 +11,7 @@ typedef struct ui_bridge_data UIBridgeData;
 typedef void(*ui_main_fn)(UIBridgeData *bridge, UI *ui);
 struct ui_bridge_data {
   UI bridge;  // actual UI passed to ui_attach
-  UI *ui;     // UI pointer that will have it's callback called in
+  UI *ui;     // UI pointer that will have its callback called in
               // another thread
   event_scheduler scheduler;
   uv_thread_t ui_thread;