5 files changed, 24 insertions, 34 deletions
diff --git a/src/clint.py b/src/clint.py
index 1a355e0218..4829a50887 100755
--- a/src/clint.py
+++ b/src/clint.py
@@ -1,5 +1,7 @@
 #!/usr/bin/env python3
 #
+# https://github.com/cpplint/cpplint
+#
 # Copyright (c) 2009 Google Inc. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -29,15 +31,9 @@
 
 """Lints C files in the Neovim source tree.
 
-The goal of this script is to identify places in the code that *may*
-be in non-compliance with Neovim style.  It does not attempt to fix
-up these problems -- the point is to educate.  It does also not
-attempt to find all problems, or to ensure that everything it does
-find is legitimately a problem.
-
-In particular, we can get very confused by /* and // inside strings!
-We do a small hack, which is to ignore //'s with "'s after them on the
-same line, but it is far from perfect (in either direction).
+This can get very confused by /* and // inside strings! We do a small hack,
+which is to ignore //'s with "'s after them on the same line, but it is far
+from perfect (in either direction).
 """
 
 
@@ -61,25 +57,10 @@ Syntax: clint.py [--verbose=#] [--output=vs7] [--filter=-x,+y,...]
         <file> [file] ...
 
   The style guidelines this tries to follow are those in
-    http://neovim.io/develop/style-guide.xml
-
-  Note: This is Google's cpplint.py modified for use with the Neovim project,
-  which follows the Google C++ coding convention except with the following
-  modifications:
-
-   * Function names are lower_case.
-   * Struct and enum names that are not typedef-ed are struct lower_case and
-     enum lower_case.
-   * The opening brace for functions appear on the next line.
-   * All control structures must always use braces.
-
-  Neovim is a C project. As a result, for .c and .h files, the following rules
-  are suppressed:
+    https://neovim.io/doc/user/dev_style.html#dev-style
 
-   * [whitespace/braces] { should almost always be at the end of the previous
-     line
-   * [build/include] Include the directory when naming .h files
-   * [runtime/int] Use int16_t/int64_t/etc, rather than the C type.
+  Note: This is Google's https://github.com/cpplint/cpplint modified for use
+  with the Neovim project.
 
   Every problem is given a confidence score from 1-5, with 5 meaning we are
   certain of the problem, and 1 meaning it could be a legitimate construct.
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 6f8cad3e33..51fedb302a 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -355,6 +355,8 @@ static bool check_string_array(Array arr, bool disallow_nl, Error *err)
 /// Out-of-bounds indices are clamped to the nearest valid value, unless
 /// `strict_indexing` is set.
 ///
+/// @see |nvim_buf_set_text()|
+///
 /// @param channel_id
 /// @param buffer           Buffer handle, or 0 for current buffer
 /// @param start            First line index
@@ -527,6 +529,8 @@ end:
 ///
 /// Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines.
 ///
+/// @see |nvim_buf_set_lines()|
+///
 /// @param channel_id
 /// @param buffer           Buffer handle, or 0 for current buffer
 /// @param start_row        First line index
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index aaff00d640..08dcc113da 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -51,7 +51,9 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
   win_set_buf(window, buffer, false, err);
 }
 
-/// Gets the (1,0)-indexed cursor position in the window. |api-indexing|
+/// Gets the (1,0)-indexed, buffer-relative cursor position for a given window
+/// (different windows showing the same buffer have independent cursor
+/// positions). |api-indexing|
 ///
 /// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
diff --git a/src/nvim/hashtab.c b/src/nvim/hashtab.c
index 32d67621db..1ebac603c2 100644
--- a/src/nvim/hashtab.c
+++ b/src/nvim/hashtab.c
@@ -194,7 +194,7 @@ void hash_debug_results(void)
 #endif  // ifdef HT_DEBUG
 }
 
-/// Add item for key "key" to hashtable "ht".
+/// Add (empty) item for key `key` to hashtable `ht`.
 ///
 /// @param key Pointer to the key for the new item. The key has to be contained
 ///            in the new item (@see hashitem_T). Must not be NULL.
diff --git a/src/nvim/terminal.c b/src/nvim/terminal.c
index e54a1c8334..50574b292d 100644
--- a/src/nvim/terminal.c
+++ b/src/nvim/terminal.c
@@ -111,9 +111,9 @@ struct terminal {
   //  - receive data from libvterm as a result of key presses.
   char textbuf[0x1fff];
 
-  ScrollbackLine **sb_buffer;       // Scrollback buffer storage for libvterm
-  size_t sb_current;                // number of rows pushed to sb_buffer
-  size_t sb_size;                   // sb_buffer size
+  ScrollbackLine **sb_buffer;       // Scrollback storage.
+  size_t sb_current;                // Lines stored in sb_buffer.
+  size_t sb_size;                   // Capacity of sb_buffer.
   // "virtual index" that points to the first sb_buffer row that we need to
   // push to the terminal buffer when refreshing the scrollback. When negative,
   // it actually points to entries that are no longer in sb_buffer (because the
@@ -154,7 +154,7 @@ static VTermScreenCallbacks vterm_screen_callbacks = {
   .movecursor  = term_movecursor,
   .settermprop = term_settermprop,
   .bell        = term_bell,
-  .sb_pushline = term_sb_push,
+  .sb_pushline = term_sb_push,  // Called before a line goes offscreen.
   .sb_popline  = term_sb_pop,
 };
 
@@ -952,7 +952,10 @@ static int term_bell(void *data)
   return 1;
 }
 
-// Scrollback push handler (from pangoterm).
+/// Scrollback push handler: called just before a line goes offscreen (and libvterm will forget it),
+/// giving us a chance to store it.
+///
+/// Code adapted from pangoterm.
 static int term_sb_push(int cols, const VTermScreenCell *cells, void *data)
 {
   Terminal *term = data;