improve comments

The new diagrams are different due to changes that have happened since
they were last generated.

src/terminal/Screen.zig

@@ -779,8 +779,8 @@ pub fn cursorDownScroll(self: *Screen) !void {
     }
 }
 
-/// This scrolls the active area at and above the cursor. The lines below
+/// This scrolls the active area at and above the cursor.
-/// the cursor are not scrolled.
+/// The lines below the cursor are not scrolled.
 pub fn cursorScrollAbove(self: *Screen) !void {
     // If the cursor is on the bottom of the screen, its faster to use
     // our specialized function for that case.
@@ -793,6 +793,14 @@ pub fn cursorScrollAbove(self: *Screen) !void {
     // Logic below assumes we always have at least one row that isn't moving
     assert(self.cursor.y < self.pages.rows - 1);
 
+    // Explanation:
+    //  We don't actually move everything that's at or above the cursor row,
+    //  since this would require us to shift up our ENTIRE scrollback, which
+    //  would be ridiculously expensive. Instead, we insert a new row at the
+    //  end of the pagelist (`grow()`), and move everything BELOW the cursor
+    //  DOWN by one row. This has the same practical result but it's a whole
+    //  lot cheaper in 99% of cases.
+
     const old_pin = self.cursor.page_pin.*;
     if (try self.pages.grow()) |_| {
         try self.cursorScrollAboveRotate();
@@ -803,6 +811,9 @@ pub fn cursorScrollAbove(self: *Screen) !void {
             // If we're on the last page we can do a very fast path because
             // all the rows we need to move around are within a single page.
 
+            // Note: we don't need to call cursorChangePin here because
+            // the pin page is the same so there is no accounting to do
+            // for styles or any of that.
             assert(old_pin.node == self.cursor.page_pin.node);
             self.cursor.page_pin.* = self.cursor.page_pin.down(1).?;
 
@@ -823,10 +834,6 @@ pub fn cursorScrollAbove(self: *Screen) !void {
             const page_rac = self.cursor.page_pin.rowAndCell();
             self.cursor.page_row = page_rac.row;
             self.cursor.page_cell = page_rac.cell;
-
-            // Note: we don't need to call cursorChangePin here because
-            // the pin page is the same so there is no accounting to do for
-            // styles or any of that.
         } else {
             // We didn't grow pages but our cursor isn't on the last page.
             // In this case we need to do more work because we need to copy
@@ -4317,8 +4324,31 @@ test "Screen: scroll above same page" {
     try s.testWriteString("1ABCD\n2EFGH\n3IJKL");
     s.cursorAbsolute(0, 1);
     s.pages.clearDirty();
+
+    // At this point:
+    //  +-------------+ ACTIVE
+    //   +----------+ : = PAGE 0
+    // 0 |1ABCD00000| | 0
+    // 1 |2EFGH00000| | 1
+    //   :^         : : = PIN 0
+    // 2 |3IJKL00000| | 2
+    //   +----------+ :
+    //  +-------------+
+
     try s.cursorScrollAbove();
 
+    //   +----------+ = PAGE 0
+    // 0 |1ABCD00000|
+    //  +-------------+ ACTIVE
+    // 1 |2EFGH00000| | 0
+    // 2 |          | | 1
+    //   :^         : : = PIN 0
+    // 3 |3IJKL00000| | 2
+    //   +----------+ :
+    //  +-------------+
+
+    // try s.pages.diagram(std.io.getStdErr().writer());
+
     {
         const contents = try s.dumpStringAlloc(alloc, .{ .viewport = .{} });
         defer alloc.free(contents);
@@ -4368,8 +4398,25 @@ test "Screen: scroll above same page but cursor on previous page" {
     //      +----------+ = PAGE 0
     //  ... :          :
     //     +-------------+ ACTIVE
-    // 4303 |1A00000000| | 0
+    // 4305 |1A00000000| | 0
-    // 4304 |2B00000000| | 1
+    // 4306 |2B00000000| | 1
+    //      :^         : : = PIN 0
+    // 4307 |3C00000000| | 2
+    //      +----------+ :
+    //      +----------+ : = PAGE 1
+    //    0 |4D00000000| | 3
+    //    1 |5E00000000| | 4
+    //      +----------+ :
+    //     +-------------+
+
+    try s.cursorScrollAbove();
+
+    //      +----------+ = PAGE 0
+    //  ... :          :
+    // 4305 |1A00000000|
+    //     +-------------+ ACTIVE
+    // 4306 |2B00000000| | 0
+    // 4307 |          | | 1
     //      :^         : : = PIN 0
     //      +----------+ :
     //      +----------+ : = PAGE 1
@@ -4379,7 +4426,7 @@ test "Screen: scroll above same page but cursor on previous page" {
     //      +----------+ :
     //     +-------------+
 
-    try s.cursorScrollAbove();
+    // try s.pages.diagram(std.io.getStdErr().writer());
 
     {
         const contents = try s.dumpStringAlloc(alloc, .{ .viewport = .{} });
@@ -4428,8 +4475,8 @@ test "Screen: scroll above same page but cursor on previous page last row" {
     //      +----------+ = PAGE 0
     //  ... :          :
     //     +-------------+ ACTIVE
-    // 4303 |1A00000000| | 0
+    // 4306 |1A00000000| | 0
-    // 4304 |2B00000000| | 1
+    // 4307 |2B00000000| | 1
     //      :^         : : = PIN 0
     //      +----------+ :
     //      +----------+ : = PAGE 1
@@ -4443,9 +4490,9 @@ test "Screen: scroll above same page but cursor on previous page last row" {
 
     //      +----------+ = PAGE 0
     //  ... :          :
-    // 4303 |1A00000000|
+    // 4306 |1A00000000|
     //     +-------------+ ACTIVE
-    // 4304 |2B00000000| | 0
+    // 4307 |2B00000000| | 0
     //      +----------+ :
     //      +----------+ : = PAGE 1
     //    0 |          | | 1
@@ -4508,8 +4555,34 @@ test "Screen: scroll above creates new page" {
 
     // Ensure we're still on the first page
     try testing.expect(s.cursor.page_pin.node == s.pages.pages.first.?);
+
+    // At this point:
+    //      +----------+ = PAGE 0
+    //  ... :          :
+    //     +-------------+ ACTIVE
+    // 4305 |1ABCD00000| | 0
+    // 4306 |2EFGH00000| | 1
+    //      :^         : : = PIN 0
+    // 4307 |3IJKL00000| | 2
+    //      +----------+ :
+    //     +-------------+
     try s.cursorScrollAbove();
 
+    //      +----------+ = PAGE 0
+    //  ... :          :
+    // 4305 |1ABCD00000|
+    //     +-------------+ ACTIVE
+    // 4306 |2EFGH00000| | 0
+    // 4307 |          | | 1
+    //      :^         : : = PIN 0
+    //      +----------+ :
+    //      +----------+ : = PAGE 1
+    //    0 |3IJKL00000| | 2
+    //      +----------+ :
+    //     +-------------+
+
+    // try s.pages.diagram(std.io.getStdErr().writer());
+
     {
         const contents = try s.dumpStringAlloc(alloc, .{ .viewport = .{} });
         defer alloc.free(contents);
@@ -4548,8 +4621,31 @@ test "Screen: scroll above no scrollback bottom of page" {
     try s.testWriteString("1ABCD\n2EFGH\n3IJKL");
     s.cursorAbsolute(0, 1);
     s.pages.clearDirty();
+
+    // At this point:
+    //  +-------------+ ACTIVE
+    //   +----------+ : = PAGE 0
+    // 0 |1ABCD00000| | 0
+    // 1 |2EFGH00000| | 1
+    //   :^         : : = PIN 0
+    // 2 |3IJKL00000| | 2
+    //   +----------+ :
+    //  +-------------+
+
     try s.cursorScrollAbove();
 
+    //   +----------+ = PAGE 0
+    // 0 |1ABCD00000|
+    //  +-------------+ ACTIVE
+    // 1 |2EFGH00000| | 0
+    // 2 |          | | 1
+    //   :^         : : = PIN 0
+    // 3 |3IJKL00000| | 2
+    //   +----------+ :
+    //  +-------------+
+
+    //try s.pages.diagram(std.io.getStdErr().writer());
+
     {
         const contents = try s.dumpStringAlloc(alloc, .{ .viewport = .{} });
         defer alloc.free(contents);