4 files changed, 16 insertions, 7 deletions
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;