Moving comments to docstrings

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