Add comments describing tui_ui_out and its fields, cleanup a bit

This commit add comments describing tui_ui_out and its fields, and
cleans up the code a little bit.

Also switch to using in-class initialization so that the initial
values can be seen alongside the comments.

I see no reason for initializing m_line as -1 instead of 0, since all
the checks in the .c file are of the form "> 0".  AFAICS there's no
practical difference between -1 and 0.  So it seems simpler to
initialize it as 0.

There's a bit of redundancy in tui_ui_out::do_field_string, which is
fixed by this commit.

gdb/ChangeLog:
2019-03-19  Pedro Alves  <palves@redhat.com>

	* tui/tui-out.c (tui_ui_out::do_field_string): Simplify.
	(tui_ui_out::do_text): Add comments.  Reset M_LINE to 0 instead of
	to -1.  Fix TABs vs spaces.
	(tui_ui_out::tui_ui_out): Don't initialize fields here.
	* tui/tui-out.h (tui_ui_out) Add intro comments.
	<m_line, m_start_of_line>: In-class initialize, and add describing
	comment.

2 files changed, 32 insertions, 16 deletions

diff --git a/gdb/tui/tui-out.c b/gdb/tui/tui-out.c
index dd37736..5fabff2 100644
--- a/gdb/tui/tui-out.c
+++ b/gdb/tui/tui-out.c
@@ -57,17 +57,13 @@ tui_ui_out::do_field_string (int fldno, int width, ui_align align,
   if (suppress_output ())
     return;
 
+  m_start_of_line++;
+
   if (fldname && m_line > 0 && strcmp (fldname, "fullname") == 0)
     {
-      m_start_of_line++;
-      if (m_line > 0)
-        {
-          tui_show_source (string, m_line);
-        }
+      tui_show_source (string, m_line);
       return;
     }
-  
-  m_start_of_line++;
 
   cli_ui_out::do_field_string (fldno, width, align, fldname, string, style);
 }
@@ -94,11 +90,16 @@ tui_ui_out::do_text (const char *string)
   m_start_of_line++;
   if (m_line > 0)
     {
+      /* Printing a source line, so suppress regular output -- the
+	 line was shown on the TUI's source window by tui_show_source
+	 above instead.  */
       if (strchr (string, '\n') != 0)
-        {
-          m_line = -1;
-          m_start_of_line = 0;
-        }
+	{
+	  /* We've reached the end of the line, so go back to letting
+	     text output go to the console.  */
+	  m_line = 0;
+	  m_start_of_line = 0;
+	}
       return;
     }
   if (strchr (string, '\n'))
@@ -108,9 +109,7 @@ tui_ui_out::do_text (const char *string)
 }
 
 tui_ui_out::tui_ui_out (ui_file *stream)
-: cli_ui_out (stream, 0),
-  m_line (-1),
-  m_start_of_line (0)
+  : cli_ui_out (stream, 0)
 {
 }
 
diff --git a/gdb/tui/tui-out.h b/gdb/tui/tui-out.h
index 10311c9..edf0b91 100644
--- a/gdb/tui/tui-out.h
+++ b/gdb/tui/tui-out.h
@@ -20,6 +20,10 @@
 
 #include "cli-out.h"
 
+/* A ui_out class for the TUI.  This is just like the CLI's ui_out,
+   except that it overrides output methods to detect when a source
+   line is being printed and show the source in the TUI's source
+   window instead of printing the line in the console window.  */
 class tui_ui_out : public cli_ui_out
 {
 public:
@@ -39,8 +43,21 @@ protected:
 
 private:
 
-  int m_line;
-  int m_start_of_line;
+  /* These fields are used to make print_source_lines show the source
+     in the TUI's source window instead of in the console.
+     M_START_OF_LINE is incremented whenever something is output to
+     the ui_out.  If an integer field named "line" is printed on the
+     ui_out, and nothing else has been printed yet (both
+     M_START_OF_LINE and M_LINE are still 0), we assume
+     print_source_lines is starting to print a source line, and thus
+     record the line number in M_LINE.  Afterwards, when we see a
+     string field named "fullname" being output, we take the fullname
+     and the recorded line and show the source line in the TUI's
+     source window.  tui_ui_out::do_text() suppresses text output
+     until it sees an endline being printed, at which point these
+     variables are reset back to 0.  */
+  int m_line = 0;
+  int m_start_of_line = 0;
 };
 
 extern tui_ui_out *tui_out_new (struct ui_file *stream);