Doc all pub/prot members, remove unused, add todo

- Made sure all public+protected members are documented.

- Reclassified some private -> protected:
   > vscroll_width()

- Removed signatures for unimplemented (non-existant) methods:
   > u8c_cursor(void)
   > history_use(int,bool)
   > cursor_h()

- Reclassified some protected -> private:
   > x_to_glob_col()
   > xy_to_glob_rowcol()
   > is_hist_ring_row()
   > is_disp_ring_row()
   > handle_ctrl()
   > is_printable()
   > is_ctrl()
   ..etc..
   > handle_selection_autoscroll()
   > handle_selection()
   > is_redraw_style

- Add todo for ESC 7 and ESC 8
- Small code formatting mods
- Small typos

FL/Fl_Terminal.H

@@ -313,6 +313,11 @@ public:
     COLORMASK  = (FG_XTERM | BG_XTERM)
   };
 
+  ///////////////////////////////////////////////////////////////
+  //////
+  ////// Fl_Terminal Protected Classes
+  //////
+  ///////////////////////////////////////////////////////////////
 protected:
   // Margin Class ////////////////////////////////////////////
   //
@@ -715,8 +720,12 @@ private:
     bool is_complete(void) const { return (buflen_ && (buflen_ == clen_)); }
   };
 
+  ///////////////////////////////////////////////////////////////
+  //////
+  ////// Fl_Terminal members + methods
+  //////
+  ///////////////////////////////////////////////////////////////
 private:
-  // Fl_Terminal Members
   Fl_Scrollbar *vscroll_;        // vertical scrollbar (value: rows above disp_chars[])
   int           scrollbar_size_; // local preference for scrollbar size
   CharStyle     current_style_;  // current font, attrib, color..
@@ -759,9 +768,8 @@ protected:
 private:
   void create_ring(int drows, int dcols, int hrows);
 protected:
-  Utf8Char* u8c_cursor(void);
-private:
   int  vscroll_width(void) const;
+private:
   // Tabstops
   void init_tabstops(int newsize);
   void default_tabstops(void);
@@ -787,8 +795,10 @@ private:
 protected:
   const CharStyle& current_style(void) const;
   void current_style(const CharStyle& sty);
+private:
   int  x_to_glob_col(int X, int grow, int &gcol) const;
   int  xy_to_glob_rowcol(int X, int Y, int &grow, int &gcol) const;
+protected:
   int  w_to_col(int W) const;
   int  h_to_row(int H) const;
   // API: Display clear operations
@@ -802,8 +812,10 @@ protected:
   bool get_selection(int &srow,int &scol,int &erow,int &ecol) const;
   bool is_selection(void) const;
   bool is_inside_selection(int row,int col) const;
+private:
   bool is_hist_ring_row(int grow) const;
   bool is_disp_ring_row(int grow) const;
+protected:
   int  selection_text_len(void) const;
   const char* selection_text(void) const;
   void clear_mouse_selection(void);
@@ -815,8 +827,6 @@ protected:
   void insert_char(char c, int rep);
   void delete_chars(int drow, int dcol, int rep);
   void delete_chars(int rep);
-  // History
-  void history_use(int val, bool update=true);
 public:
  // API: Terminal operations
   void clear(void);
@@ -826,9 +836,6 @@ public:
   void clear_history(void);                         // ESC [ 3 J
   void reset_terminal(void);                        // ESC c
   void cursor_home(void);                           // ESC [ 0 H
-protected:
-  // Cursor management
-  int  cursor_h(void) const;
 public:
  // API: Cursor
   void cursorfgcolor(Fl_Color val);
@@ -855,6 +862,7 @@ protected:
   void save_cursor(void);
   void restore_cursor(void);
   // Printing
+private:
   void handle_ctrl(char c);
   bool is_printable(char c);
   bool is_ctrl(char c);
@@ -887,6 +895,7 @@ protected:
   void draw_row_bg(int grow, int X, int Y) const;
   void draw_row(int grow, int Y) const;
   void draw_buff(int Y) const;
+private:
   void handle_selection_autoscroll(void);
   int  handle_selection(int e);
 public:
@@ -900,20 +909,35 @@ protected:
   //   Don't make these public, but allow internals and
   //   derived classes to maintain brevity.
   //
+  /// Return the number of rows in the ring buffer.
   inline int ring_rows(void) const { return ring_.ring_rows(); }
+  /// Return the number of columns in the ring buffer.
   inline int ring_cols(void) const { return ring_.ring_cols(); }
+  /// Return the starting row# in the ring buffer. (Always 0)
   inline int ring_srow(void) const { return ring_.ring_srow(); }
+  /// Return the ending row# in the ring buffer (Always ring_rows()-1)
   inline int ring_erow(void) const { return ring_.ring_erow(); }
+  /// Return the number of rows in the scrollback history.
   inline int hist_rows(void) const { return ring_.hist_rows(); }
+  /// Return the number of columns in the scrollback history.
   inline int hist_cols(void) const { return ring_.hist_cols(); }
+  /// Return the starting row# of the scrollback history.
   inline int hist_srow(void) const { return ring_.hist_srow(); }
+  /// Return the ending row# of the scrollback history.
   inline int hist_erow(void) const { return ring_.hist_erow(); }
+  /// Return number of rows in use by the scrollback history.
   inline int hist_use(void)  const { return ring_.hist_use();  }
+  /// Return the starting row of the "in use" scrollback history.
   inline int hist_use_srow(void) const { return ring_.hist_use_srow(); }
+  /// Return the number of rows in the display area.
   inline int disp_rows(void) const { return ring_.disp_rows(); }
+  /// Return the number of columns in the display area.
   inline int disp_cols(void) const { return ring_.disp_cols(); }
+  /// Return the starting row# in the display area.
   inline int disp_srow(void) const { return ring_.disp_srow(); }
+  /// Return the ending row# in the display area.
   inline int disp_erow(void) const { return ring_.disp_erow(); }
+  /// Returns the current offset into the ring buffer.
   inline int offset(void) const    { return ring_.offset(); }
 
   // TODO: CLEAN UP WHAT'S PUBLIC, AND WHAT SHOULD BE 'PROTECTED' AND 'PRIVATE'
@@ -959,21 +983,21 @@ public:
   void  margin_top(int val);
   void  margin_bottom(int val);
   // API: Text font/size/color
-  void        textfont(Fl_Font val);
+  void  textfont(Fl_Font val);
-  void        textsize(Fl_Fontsize val);
+  void  textsize(Fl_Fontsize val);
-  void        textcolor(Fl_Color val);
+  void  textcolor(Fl_Color val);
-  void        color(Fl_Color val);
+  void  color(Fl_Color val);
-  void        textfgcolor(Fl_Color val);
+  void  textfgcolor(Fl_Color val);
-  void        textbgcolor(Fl_Color val);
+  void  textbgcolor(Fl_Color val);
-  void        textfgcolor_default(Fl_Color val);
+  void  textfgcolor_default(Fl_Color val);
-  void        textbgcolor_default(Fl_Color val);
+  void  textbgcolor_default(Fl_Color val);
   /// Return text font used to draw all text in the terminal.
   Fl_Font     textfont(void)      const { return current_style_.fontface(); }
   /// Return text font size used to draw all text in the terminal.
   Fl_Fontsize textsize(void)      const { return current_style_.fontsize(); }
-  // Return base widget Fl_Group's box() color()
+  /// Return base widget Fl_Group's box() color()
   Fl_Color    color(void)         const { return Fl_Group::color(); }
-  // Return textcolor(). This is a convenience method that returns textfgcolor_default()
+  /// Return textcolor(). This is a convenience method that returns textfgcolor_default()
   Fl_Color    textcolor(void)     const { return textfgcolor_default(); }
   /// Return text's current foreground color.
   Fl_Color    textfgcolor(void)   const { return current_style_.fgcolor(); }
@@ -998,7 +1022,7 @@ public:
   // API: Redraw style/rate
   RedrawStyle redraw_style(void) const;
   void  redraw_style(RedrawStyle val);
-protected:
+private:
   bool  is_redraw_style(RedrawStyle val) { return redraw_style_ == val; }
 public:
   float redraw_rate(void) const;

src/Fl_Terminal.cxx

@@ -328,7 +328,7 @@ void Fl_Terminal::EscapeSeq::save_cursor(int row, int col) {
   save_col_ = col;
 }
 
-// Return saved position in row,col
+// Restore last saved cursor position into row,col
 void Fl_Terminal::EscapeSeq::restore_cursor(int &row, int &col) {
   row = save_row_;
   col = save_col_;
@@ -1023,12 +1023,7 @@ void Fl_Terminal::create_ring(int drows, int dcols, int hrows) {
   cursor_.home();
 }
 
-// Return the Utf8Char* for character under cursor.
+/// Return scrollbar width if visible, or 0 if not visible.
-Fl_Terminal::Utf8Char* Fl_Terminal::u8c_cursor(void) {
-  return u8c_disp_row(cursor_.row()) + cursor_.col();
-}
-
-// Return scrollbar width if visible, or 0 if not visible
 int Fl_Terminal::vscroll_width(void) const {
   return(vscroll_->visible() ? vscroll_->w() : 0);
 }
@@ -1555,9 +1550,12 @@ void Fl_Terminal::textattrib(uchar val) {
   current_style_.attrib(val);
 }
 
-// Convert fltk window X coord to column 'gcol' on specified global 'grow'
+/**
-//     Returns 1 if 'gcol' was found, or 0 if X not within any char in 'grow'
+  Convert fltk window X coord to column 'gcol' on specified global 'grow'
-//
+  \returns
+    - 1 if 'gcol' was found
+    - 0 if X not within any char in 'grow'
+*/
 int Fl_Terminal::x_to_glob_col(int X, int grow, int &gcol) const {
   int cx = x() + margin_.left();                    // char x position
   const Utf8Char *u8c = utf8_char_at_glob(grow, 0);
@@ -1790,11 +1788,13 @@ bool Fl_Terminal::get_selection(int &srow,  ///< starting row for selection
   return select_.get_selection(srow, scol, erow, ecol);
 }
 
-// Is global row,col (relative to ring_chars[]) inside the current mouse selection?
+/**
-// Retruns:
+  Is global row/column inside the current mouse selection?
-//    true  -- (row,col) inside a valid selection.
+
-//    false -- (row,col) outside, or no valid selection.
+  \returns
-//
+  - true  -- (\p grow, \p gcol) is inside a valid selection.
+  - false -- (\p grow, \p gcol) is outside, or no valid selection.
+*/
 bool Fl_Terminal::is_inside_selection(int grow, int gcol) const {
   if (!is_selection()) return false;
   int ncols = ring_cols();
@@ -1830,9 +1830,10 @@ bool Fl_Terminal::is_disp_ring_row(int grow) const {
   return ring_.is_disp_ring_row(grow);
 }
 
-// Return byte length of all UTF-8 chars in selection, or 0 if no selection.
+/**
-//    NOTE: Length includes trailing white on each line.
+  Return byte length of all UTF-8 chars in selection, or 0 if no selection.
-//
+  NOTE: Length includes trailing white on each line.
+*/
 int Fl_Terminal::selection_text_len(void) const {
   int row,col,len=0;
   const Utf8Char *u8c = NULL;                     // start with NULL to begin walk
@@ -1841,11 +1842,12 @@ int Fl_Terminal::selection_text_len(void) const {
   return len;
 }
 
-// Return text selection (for copy()/paste() operations)
+/**
-//     Returns allocated NULL terminated string for entire selection.
+  Return text selection (for copy()/paste() operations)
-//     Caller must free() this memory when done.
+  - Returns allocated NULL terminated string for entire selection.
-//     Unicode safe.
+  - Caller must free() this memory when done.
-//
+  - Unicode safe.
+*/
 const char* Fl_Terminal::selection_text(void) const {
   if (!is_selection()) return fl_strdup("");             // no selection? empty string
   // Allocate buff large enough for all UTF-8 chars
@@ -1875,14 +1877,15 @@ const char* Fl_Terminal::selection_text(void) const {
   return buf;
 }
 
-// Clear mouse selection
+/// Clear any current mouse selection.
 void Fl_Terminal::clear_mouse_selection(void) {
   select_.clear();
 }
 
-// Extend selection to FLTK coords X,Y.
+/**
-//    Returns true if extended, false if nothing done (X,Y offscreen)
+  Extend selection to FLTK coords X,Y.
-//
+  Returns true if extended, false if nothing done (X,Y offscreen)
+*/
 bool Fl_Terminal::selection_extend(int X,int Y) {
   if (is_selection()) {                  // selection already?
     int grow,gcol;
@@ -1897,10 +1900,12 @@ bool Fl_Terminal::selection_extend(int X,int Y) {
   return false;
 }
 
-// Scroll the display up(+) or down(-) number of rows.
+/**
-//     Negative row value scrolls "down", clearing top line, and history unaffected.
+  Scroll the display up(+) or down(-) the specified \p rows.
-//     Postive row value scrolls "up", clearing bottom line, rotating top line into history.
+
-//
+  - Negative value scrolls "down", clearing top line, and history unaffected.
+  - Postive value scrolls "up", clearing bottom line, rotating top line into history.
+*/
 void Fl_Terminal::scroll(int rows) {
   // Scroll the ring
   ring_.scroll(rows, current_style_);
@@ -1908,10 +1913,11 @@ void Fl_Terminal::scroll(int rows) {
   else          clear_mouse_selection(); // scroll dn? clear mouse select; it might wrap ring
 }
 
-// Insert (count) rows at cursor position.
+/**
-//    Causes rows below to scroll down, and empty lines created.
+  Insert (count) rows at current cursor position.
-//    Scrolling does not involve history at all.
+  Causes rows below to scroll down, and empty lines created.
-//
+  Lines deleted by scroll down are NOT moved into the scroll history.
+*/
 void Fl_Terminal::insert_rows(int count) {
   int dst_drow = disp_rows()-1;                                   // dst is bottom of display
   int src_drow = clamp((dst_drow-count), 1, (disp_rows()-1));     // src is count lines up from dst
@@ -1929,10 +1935,11 @@ void Fl_Terminal::insert_rows(int count) {
   clear_mouse_selection();
 }
 
-// Delete (count) rows at cursor position.
+/**
-//    Causes rows to scroll up, and empty lines created at bottom of screen.
+ Delete (count) rows at cursor position.
-//    Scrolling does not involve history at all.
+ Causes rows to scroll up, and empty lines created at bottom of screen.
-//
+ Lines deleted by scroll up are NOT moved into the scroll history.
+*/
 void Fl_Terminal::delete_rows(int count) {
   int dst_drow = cursor_.row();                                   // dst is cursor row
   int src_drow = clamp((dst_drow+count), 1, (disp_rows()-1));     // src is count rows below cursor
@@ -1957,7 +1964,7 @@ void Fl_Terminal::repeat_char(char c, int rep) {
   while ( rep-- > 0 && cursor_.col() < disp_cols() ) print_char(c);
 }
 
-// Insert char 'c' for 'rep' times at display (drow,dcol).
+/// Insert char 'c' for 'rep' times at display row \p 'drow' and column \p 'dcol'.
 void Fl_Terminal::insert_char_eol(char c, int drow, int dcol, int rep) {
   // Walk the row from the eol backwards to the col position
   //     In this example, rep=3:
@@ -1983,14 +1990,15 @@ void Fl_Terminal::insert_char_eol(char c, int drow, int dcol, int rep) {
   }
 }
 
-// Insert char 'c' for 'rep' times.
+/**
-//     Does not wrap; characters at end of line are lost.
+  Insert char 'c' at the current cursor position for 'rep' times.
-//
+  Does not wrap; characters at end of line are lost.
+*/
 void Fl_Terminal::insert_char(char c, int rep) {
   insert_char_eol(c, cursor_.row(), cursor_.col(), rep);
 }
 
-// Delete char(s) at (drow,dcol) for 'rep' times.
+/// Delete char(s) at (drow,dcol) for 'rep' times.
 void Fl_Terminal::delete_chars(int drow, int dcol, int rep) {
   rep = clamp(rep, 0, disp_cols());                // sanity
   if (rep == 0) return;
@@ -2001,7 +2009,7 @@ void Fl_Terminal::delete_chars(int drow, int dcol, int rep) {
     else                        u8c[col] = u8c[col+rep];          // move
 }
 
-// Delete char(s) at cursor position for 'rep' times.
+/// Delete char(s) at cursor position for 'rep' times.
 void Fl_Terminal::delete_chars(int rep) {
   delete_chars(cursor_.row(), cursor_.col(), rep);
 }
@@ -2043,12 +2051,12 @@ void Fl_Terminal::reset_terminal(void) {
 //DEBUG   ::printf("\033[05C   ring_rows_: %d\n", ring_rows_);
 //DEBUG   ::printf("\033[05C   ring_cols_: %d\n", ring_cols_);
 //DEBUG   ::printf("\033[05C      offset_: %d\n", offset_);
-//DEBUG   ::printf("\033[u"); // recall cursor
+//DEBUG   ::printf("\033[u"); // restore cursor
 //DEBUG   ::printf("\033[30C -- History Index\n");
 //DEBUG   ::printf("\033[30C   hist_rows_: %d srow=%d\n", hist_rows(), hist_srow());
 //DEBUG   ::printf("\033[30C   hist_cols_: %d erow=%d\n", hist_cols(), hist_erow());
 //DEBUG   ::printf("\033[30C    hist_use_: %d\n",         hist_use());
-//DEBUG   ::printf("\033[u"); // recall cursor
+//DEBUG   ::printf("\033[u"); // restore cursor
 //DEBUG   ::printf("\033[60C -- Display Index\n");
 //DEBUG   ::printf("\033[60C   disp_rows_: %d srow=%d\n", disp_rows(), disp_srow());
 //DEBUG   ::printf("\033[60C   disp_cols_: %d erow=%d\n", disp_cols(), disp_erow());
@@ -2206,7 +2214,7 @@ void Fl_Terminal::cursor_crlf(int count) {
   cursor_down(count, do_scroll);
 }
 
-// Tab right, do not wrap beyond right edge
+/// Tab right, do not wrap beyond right edge.
 void Fl_Terminal::cursor_tab_right(int count) {
   count = clamp(count, 1, disp_cols());           // sanity
   int X = cursor_.col();
@@ -2220,7 +2228,7 @@ void Fl_Terminal::cursor_tab_right(int count) {
   cursor_eol();
 }
 
-// Tab left, do not wrap beyond left edge
+/// Tab left, do not wrap beyond left edge.
 void Fl_Terminal::cursor_tab_left(int count) {
   count = clamp(count, 1, disp_cols());           // sanity
   int X = cursor_.col();
@@ -2231,16 +2239,16 @@ void Fl_Terminal::cursor_tab_left(int count) {
   cursor_sol();
 }
 
-// Save current cursor position
+/// Save current cursor position. Used by ESC [ s
 void Fl_Terminal::save_cursor(void) {
   escseq.save_cursor(cursor_.row(), cursor_.col());
 }
 
-// Restore previously saved cursor position, if there was one
+/// Restore previously saved cursor position, if any. Used by ESC [ u
 void Fl_Terminal::restore_cursor(void) {
   int row,col;
   escseq.restore_cursor(row, col);
-  if (row != -1 && col != 1)                      // restore only if save first
+  if (row != -1 && col != 1)         // restore only if previously saved
     { cursor_.row(row); cursor_.col(col); }
 }
 
@@ -2248,6 +2256,18 @@ void Fl_Terminal::restore_cursor(void) {
 ////// PRINTING //////
 //////////////////////
 
+/**
+  Handle the special control character 'c'.
+
+  These are control characters that involve special terminal handling, e.g.
+  \code
+  \r - carriage return - cursor_cr()
+  \n - line feed       - cursor_crlf() - default behavior for \n is CR and LF
+  \b - backspace       - cursor_left()
+  \t - tab             - cursor_tab_right()
+  \e - escape          - starts an ANSI or xterm escape sequence
+  \endcode
+*/
 void Fl_Terminal::handle_ctrl(char c) {
   switch (c) {
     case '\n': cursor_crlf();              return;  // CRLF?
@@ -2358,18 +2378,28 @@ void Fl_Terminal::handle_SGR(void) {     // ESC[...m?
   }
 }
 
-// Handle <ESC>[<top>;<lt>;<bot>;<rt>;<att>$t
+/**
-//     This one is fun! <att> is the attrib to xor, i.e. 1(bold),4,5,7(inverse).
+  Handle the VT100 sequence <tt>ESC [ top ; lt ; bot ; rt ; att $ t</tt>
-//     gnome-term doesn't support this, but xterm does.
+
-//
+  top/lt/bot/rt is the screen area to affect, 'att' is the attrib to xor,
+  i.e. 1(bold),4,5,7(inverse).
+
+  \note
+    - gnome-term doesn't support this, but xterm does.
+    - Currently unsupported by Fl_Terminal
+*/
 void Fl_Terminal::handle_DECRARA(void) {
   // TODO: MAYBE NEVER
 }
 
-// Handle an escape sequence character
+/**
-//    If this char is the end of the sequence, do the operation
+  Handle an escape sequence character.
-//    if possible, and then reset() to finish parsing.
+
-//
+  Call this on a character only if escseq.parse_in_progress() is true.
+
+  If this char is the end of the sequence, do the operation (if possible),
+  then does an escseq.reset() to finish parsing.
+*/
 void Fl_Terminal::handle_escseq(char c) {
   // NOTE: Use xterm to test. gnome-terminal has bugs, even in 2022.
   const bool do_scroll = true;
@@ -2522,7 +2552,7 @@ cup:
         break;
       case 'm': handle_SGR();             break; // ESC[#m - set character attributes (SGR)
       case 's': save_cursor();            break; // ESC[s - save cur pos (xterm+gnome)
-      case 'u': restore_cursor();         break; // ESC[u - rest cur pos (xterm+gnome)
+      case 'u': restore_cursor();         break; // ESC[u - restore cur pos (xterm+gnome)
       case 'q':  // TODO?                        // ESC[>#q set cursor style (block/line/blink..)
       case 'r':  // TODO                         // ESC[#;#r set scroll region top;bot
                                                  // default=full window
@@ -2537,13 +2567,13 @@ cup:
   } else {
     // Not CSI? Might be C1 Control code (<ESC>D, etc)
     switch ( esc.esc_mode() ) {
-      case 'c':                                  // <ESC>c - Reset term to Initial State (RIS)
+      case 'c': reset_terminal();          break;// <ESC>c - Reset term to Initial State (RIS)
-        reset_terminal();
-        break;
       case 'D': cursor_down(1, do_scroll); break;// <ESC>D - down line, scroll at bottom
       case 'E': cursor_crlf();             break;// <ESC>E - do a crlf
       case 'H': set_tabstop();             break;// <ESC>H - set a tabstop
-      case 'M': cursor_up(1, true);        break;// <ESC>M -- (RI) Reverse Index (up w/scroll)
+      case 'M': cursor_up(1, true);        break;// <ESC>M - (RI) Reverse Index (up w/scroll)
+      case '7': handle_unknown_char();     break;// <ESC>7 - Save cursor & attrs    // TODO
+      case '8': handle_unknown_char();     break;// <ESC>8 - Restore cursor & attrs // TODO
       default:
         handle_unknown_char();                   // does an escseq.reset()
         break;
@@ -2552,11 +2582,18 @@ cup:
   esc.reset();   // done handling escseq, reset()
 }
 
+/**
+  Clears that the display has been modified; sets internal
+  redraw_modified_ to false.
+*/
 void Fl_Terminal::display_modified_clear(void) {
   redraw_modified_ = false;
 }
 
-// Display modified, trigger redraw handling..
+/**
+  Flag that the display has been modified, triggering redraws.
+  Sets the internal redraw_modified_ flag to true.
+*/
 void Fl_Terminal::display_modified(void) {
   if (is_redraw_style(RATE_LIMITED)) {
     if (!redraw_modified_) {                         // wasn't before but now is?
@@ -3060,10 +3097,16 @@ void Fl_Terminal::scrollbar_size(int val) {
 ////// SCREEN DRAWING //////
 ////////////////////////////
 
-// Draw the background for the specified ring_chars[] row starting at FLTK coords X,Y
+/**
-//    Note we may be called to draw display, or even history if we're scrolled back.
+  Draw the background for the specified ring_chars[] global row \p grow
-//    If there's any change in bg color, we draw the filled rects here.
+  starting at FLTK coords \p X and \p Y.
-//
+
+  Note we may be called to draw display, or even history if we're scrolled back.
+  If there's any change in bg color, we draw the filled rects here.
+
+  If the bg color for a character is the special "see through" color 0xffffffff,
+  no pixels are drawn.
+*/
 void Fl_Terminal::draw_row_bg(int grow, int X, int Y) const {
   int bg_h = current_style_.fontheight();
   int bg_y = Y - current_style_.fontheight() + current_style_.fontdescent();
@@ -3092,9 +3135,10 @@ void Fl_Terminal::draw_row_bg(int grow, int X, int Y) const {
   }
 }
 
-// Draw specified global row, which is the row in ring_chars[].
+/**
-//    The global row includes history + display buffers.
+  Draw the specified global row, which is the row in ring_chars[].
-//
+  The global row includes history + display buffers.
+*/
 void Fl_Terminal::draw_row(int grow, int Y) const {
   // Draw background color spans, if any
   int X = scrn_.x();
@@ -3155,13 +3199,15 @@ void Fl_Terminal::draw_row(int grow, int Y) const {
   }
 }
 
-// Draw the part of the buffer we're scrolled to at FLTK position Y.
+/**
-//
+  Draws the buffer position we are scrolled to onto the FLTK screen
-//    This could be anywhere in the buffer, and not just the 'active diplay',
+  starting at pixel position Y.
-//    depending on what the scrollbar is set to.
+
-//
+  This can be anywhere in the ring buffer, not just the 'active diplay';
-//    Handles attributes, colors, text selections, cursor.
+  depends on what position the scrollbar is set to.
-//
+
+  Handles attributes, colors, text selections, cursor.
+*/
 void Fl_Terminal::draw_buff(int Y) const {
   int srow = disp_srow() - vscroll_->value();
   int erow = srow + disp_rows();
@@ -3204,12 +3250,18 @@ void Fl_Terminal::draw(void) {
   fl_pop_clip();
 }
 
-// Given a width in pixels, return number of columns that "fits"
+/**
+  Given a width in pixels, return number of columns that "fits" into that area.
+  This is used by the constructor to size the row/cols to fit the widget size.
+*/
 int Fl_Terminal::w_to_col(int W) const {
   return int((float(W) / current_style_.charwidth()) + 0.0);    // +.5 overshoots
 }
 
-// Given a height in pixels, return number of rows that "fits"
+/**
+  Given a height in pixels, return number of rows that "fits" into that area.
+  This is used by the constructor to size the row/cols to fit the widget size.
+*/
 int Fl_Terminal::h_to_row(int H) const {
   return int((float(H) / current_style_.fontheight()) + -0.5);  // +.5 overshoots
 }
@@ -3254,9 +3306,10 @@ void Fl_Terminal::handle_selection_autoscroll(void) {
   }
 }
 
-// Handle mouse selection on LEFT-CLICK push/drag/release
+/**
-//     Returns: 1 if 'handled', 0 if not.
+  Handle mouse selection on LEFT-CLICK push/drag/release.
-//
+  Returns: 1 if 'handled', 0 if not.
+*/
 int Fl_Terminal::handle_selection(int e) {
   int grow=0,gcol=0;
   bool is_rowcol = (xy_to_glob_rowcol(Fl::event_x(), Fl::event_y(), grow, gcol) > 0)