From 4ff822373b7daf105129b99303541bf293a3ebfb Mon Sep 17 00:00:00 2001
From: Michael Lazar <michael.lazar.ctr@dren.hpc.mil>
Date: Tue, 27 Jun 2017 23:20:05 -0400
Subject: [PATCH] Moving comments to docstrings

---
 rtv/page.py     | 10 ----------
 rtv/terminal.py | 23 +++++++++++++++++++++--
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/rtv/page.py b/rtv/page.py
index 2235604..1ee6611 100644
--- a/rtv/page.py
+++ b/rtv/page.py
@@ -390,16 +390,6 @@ class Page(object):
         self._draw_content()
         self._draw_footer()
         self._add_cursor()
-        # Note: There used to be a call to stdscr.touchwin() here. However, a
-        # bug was discovered in tmux when $TERM was set to `xterm-256color`,
-        # where only part of the screen got redrawn when scrolling. The correct
-        # solution is to use `screen-256color` (which gets set automatically by
-        # tmux) but many people override ther $TERM in their tmux.conf or
-        # .bashrc file. Using clearok() instead seems to fix the problem, at
-        # the expense of slightly more expensive screen refreshes.
-        # However clearok() introduced a screen flash bug to urxvt users so the 
-        # clear_screen() method chooses which of the two stdscr methods to use
-        # based on the $TERM environment variable
         self.term.clear_screen()
         self.term.stdscr.refresh()
 
diff --git a/rtv/terminal.py b/rtv/terminal.py
index 96698e9..6ff4526 100644
--- a/rtv/terminal.py
+++ b/rtv/terminal.py
@@ -771,10 +771,29 @@ class Terminal(object):
         out = '\n'.join(stack)
         return out
     
-    # Resolves tmux touchwin() bug and urxvt clearok() flashing bug
     def clear_screen(self):
+        """
+        In the beginning this always called touchwin(). However, a bug
+        was discovered in tmux when TERM was set to `xterm-256color`, where
+        only part of the screen got redrawn when scrolling. tmux automatically
+        sets TERM to `screen-256color`, but many people choose to override
+        this in their tmux.conf or .bashrc file which can cause issues.
+        Using clearok() instead seems to fix the problem, with the trade off
+        of slightly more expensive screen refreshes.
+               
+        Update: It was discovered that using clearok() introduced a
+        separate bug for urxvt users in which their screen flashed when
+        scrolling. Heuristics were added to make it work with as many
+        configurations as possible. It's still not perfect
+        (e.g. urxvt + xterm-256color) will screen flash, but it should
+        work in all cases if the user sets their TERM correctly.
+        
+        Reference:
+            https://github.com/michael-lazar/rtv/issues/343
+            https://github.com/michael-lazar/rtv/issues/323
+        """
+
         if self._term != 'xterm-256color':
             self.stdscr.touchwin()
         else:
             self.stdscr.clearok(True)
-