From 90d19a9cc76fd36b3155bd5d06cf72f7e76ce9a5 Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Sun, 10 Nov 2019 08:30:43 -0500
Subject: docs

---
 src/parser.rs |  3 ++-
 src/screen.rs | 31 +++++++++++++++++++++++--------
 2 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/src/parser.rs b/src/parser.rs
index 0cabb1a..5099eb9 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -6,7 +6,8 @@ pub struct Parser {
 }
 
 impl Parser {
-    /// Creates a new terminal parser of the given size.
+    /// Creates a new terminal parser of the given size and with the given
+    /// amount of scrollback.
     pub fn new(rows: u16, cols: u16, scrollback_len: usize) -> Self {
         Self {
             parser: vte::Parser::new(),
diff --git a/src/screen.rs b/src/screen.rs
index c2fef6b..57b37fb 100644
--- a/src/screen.rs
+++ b/src/screen.rs
@@ -112,14 +112,6 @@ impl Screen {
         }
     }
 
-    pub fn scrollback(&self) -> usize {
-        self.grid().scrollback()
-    }
-
-    pub fn set_scrollback(&mut self, rows: usize) {
-        self.grid_mut().set_scrollback(rows);
-    }
-
     /// Resizes the terminal.
     pub fn set_size(&mut self, rows: u16, cols: u16) {
         self.grid.set_size(crate::grid::Size { rows, cols });
@@ -135,6 +127,29 @@ impl Screen {
         (size.rows, size.cols)
     }
 
+    /// Returns the current position in the scrollback.
+    ///
+    /// This position indicates the offset from the top of the screen, and is
+    /// `0` when the normal screen is in view.
+    pub fn scrollback(&self) -> usize {
+        self.grid().scrollback()
+    }
+
+    /// Scrolls to the given position in the scrollback.
+    ///
+    /// This position indicates the offset from the top of the screen, and
+    /// should be `0` to put the normal screen in view.
+    ///
+    /// This affects the return values of methods called on `parser.screen()`:
+    /// for instance, `parser.screen().cell(0, 0)` will return the top left
+    /// corner of the screen after taking the scrollback offset into account.
+    /// It does not affect `parser.process()` at all.
+    ///
+    /// The value given will be clamped to the actual size of the scrollback.
+    pub fn set_scrollback(&mut self, rows: usize) {
+        self.grid_mut().set_scrollback(rows);
+    }
+
     /// Returns the text contents of the terminal.
     ///
     /// This will not include any formatting information, and will be in plain
-- 
cgit v1.2.3-54-g00ecf