Moving comments to docstrings

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()
 

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)
-