Fixed typos and doxygen documentation.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6582 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 438 insertions, 409 deletions

diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index 5f51924e5..c5986e0d0 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -42,18 +42,18 @@ class Fl_Image;
 typedef void (Fl_Callback )(Fl_Widget*, void*);
 /** Default callback type pointer definition for all fltk widgets */
 typedef Fl_Callback* Fl_Callback_p; // needed for BORLAND
-/** One parameter Callback type definition passing only the widget */
+/** One parameter callback type definition passing only the widget */
 typedef void (Fl_Callback0)(Fl_Widget*);
 /** Callback type definition passing the widget and a long data value */
 typedef void (Fl_Callback1)(Fl_Widget*, long);
 
 
 /** This struct stores all information for a text or mixed graphics label.
- *
- *  \todo For FLTK1.3, the Fl_Label type will become a widget by itself. That way
- *        we will be avoiding a lot of code duplication by handling labels in 
- *        a similar fashion to widgets containing text. We also provide an easy
- *        interface for very complex labels, containing html or vector graphics.
+
+    \todo For FLTK 1.3, the Fl_Label type will become a widget by itself. That way
+          we will be avoiding a lot of code duplication by handling labels in 
+          a similar fashion to widgets containing text. We also provide an easy
+          interface for very complex labels, containing html or vector graphics.
  */
 struct FL_EXPORT Fl_Label {
   /** label text */
@@ -70,23 +70,23 @@ struct FL_EXPORT Fl_Label {
   Fl_Fontsize size;
   /** text color */
   unsigned color;
-  /** draw the label aligned to the given box */
+  /** Draws the label aligned to the given box */
   void draw(int,int,int,int, Fl_Align) const ;
   void measure(int &w, int &h) const ;
 };
 
 
 /** Fl_Widget is the base class for all widgets in FLTK.  
- *
- *  You can't create one of these because the constructor is not public.  However 
- *  you can subclass it.  
- *
- *  All "property" accessing methods, such as color(), parent(), or argument() 
- *  are implemented as trivial inline functions and thus are as fast and small 
- *  as accessing fields in a structure. Unless otherwise noted, the property 
- *  setting methods such as color(n) or label(s) are also trivial inline functions, 
- *  even if they change the widget's appearance.  It is up to the user code to call 
- *  redraw() after these.
+  
+    You can't create one of these because the constructor is not public.
+    However you can subclass it.  
+
+    All "property" accessing methods, such as color(), parent(), or argument() 
+    are implemented as trivial inline functions and thus are as fast and small 
+    as accessing fields in a structure. Unless otherwise noted, the property 
+    setting methods such as color(n) or label(s) are also trivial inline 
+    functions, even if they change the widget's appearance. It is up to the 
+    user code to call redraw() after these.
  */
 class FL_EXPORT Fl_Widget {
   friend class Fl_Group;
@@ -114,24 +114,25 @@ class FL_EXPORT Fl_Widget {
 
 protected:
 
-  /** Creates a widget at the given position and size. 
-   *  The Fl_Widget is a protected constructor, but all derived widgets have a 
-   *  matching public constructor. It takes a value for x(), y(), w(), h(), and 
-   *  an optional value for label().
-   *
-   *  \param[in] x, y the position of the widget relative to the enclosing window
-   *  \param[in] w, h size of the widget in pixels
-   *  \param[in] label optional text for the widget label
+  /** Creates a widget at the given position and size.
+
+      The Fl_Widget is a protected constructor, but all derived widgets have a 
+      matching public constructor. It takes a value for x(), y(), w(), h(), and 
+      an optional value for label().
+    
+      \param[in] x, y the position of the widget relative to the enclosing window
+      \param[in] w, h size of the widget in pixels
+      \param[in] label optional text for the widget label
    */
   Fl_Widget(int x, int y, int w, int h, Fl_CString label=0L);
 
-  /** Internal use only. Use position(int,int), size(int, int) or resize(int,int,int,int) instead. */
+  /** Internal use only. Use position(int,int), size(int,int) or resize(int,int,int,int) instead. */
   void x(int v) {x_ = v;}
-  /** Internal use only. Use position(int,int), size(int, int) or resize(int,int,int,int) instead. */
+  /** Internal use only. Use position(int,int), size(int,int) or resize(int,int,int,int) instead. */
   void y(int v) {y_ = v;}
-  /** Internal use only. Use position(int,int), size(int, int) or resize(int,int,int,int) instead. */
+  /** Internal use only. Use position(int,int), size(int,int) or resize(int,int,int,int) instead. */
   void w(int v) {w_ = v;}
-  /** Internal use only. Use position(int,int), size(int, int) or resize(int,int,int,int) instead. */
+  /** Internal use only. Use position(int,int), size(int,int) or resize(int,int,int,int) instead. */
   void h(int v) {h_ = v;}
   /** Gets the widget flags mask */
   int flags() const {return flags_;}
@@ -140,7 +141,7 @@ protected:
   /** Clears a flag in the flags mask */
   void clear_flag(int c) {flags_ &= ~c;}
   /** flags possible values enumeration.
-      See activate(),output(), visible(), changed(), set_visible_focus()
+      See activate(), output(), visible(), changed(), set_visible_focus()
   */
   enum {
         INACTIVE=1,	    ///< the widget can't receive focus, and is disabled but potentially visible
@@ -149,7 +150,7 @@ protected:
         SHORTCUT_LABEL=64,  ///< the label contains a shortcut we need to draw
         CHANGED=128,	    ///< the widget value changed
         VISIBLE_FOCUS=512,  ///< accepts keyboard focus navigation if the widget can have the focus
-        COPIED_LABEL = 1024 ///< the widget label is internally copied, its destruction is handled by the widget
+        COPIED_LABEL=1024   ///< the widget label is internally copied, its destruction is handled by the widget
        };
   void draw_box() const;
   void draw_box(Fl_Boxtype, Fl_Color) const;
@@ -162,378 +163,401 @@ protected:
 
 public:
 
-  /** Destroys the widget. 
-   *  Destroying single widgets is not very common, and it is your responsibility 
-   *  to either remove() them from any enclosing group or destroy that group 
-   *  \em immediately after destroying the children. You almost always want to 
-   *  destroy the parent group instead which will destroy all of the child widgets 
-   *  and groups in that group.
+  /** Destroys the widget.
+      Destroying single widgets is not very common, and it is your responsibility 
+      to either remove() them from any enclosing group or destroy that group 
+      \em immediately after destroying the children. You almost always want to 
+      destroy the parent group instead which will destroy all of the child widgets 
+      and groups in that group.
    */
   virtual ~Fl_Widget();
 
-  /** Draw the widget.
-   *  Never call this function directly. FLTK will schedule redrawing whenever
-   *  needed. If your widget must be redrawn as soon as possible, call redraw()
-   *  instead.
-   *
-   *  Override this function to draw your own widgets.
+  /** Draws the widget.
+      Never call this function directly. FLTK will schedule redrawing whenever
+      needed. If your widget must be redrawn as soon as possible, call redraw()
+      instead.
+    
+      Override this function to draw your own widgets.
    */
   virtual void draw() = 0;
 
   /** Handles the specified event. 
-   *  You normally don't call this method directly, but instead let FLTK do 
-   *  it when the user interacts with the widget.
-   * 
-   *  When implemented in a new widget, this function must return 0 if the 
-   *  widget does not use the event or 1 otherwise.<BR>
-   *  Most of the time, you want to call the inherited handle() method in 
-   *  your overriden method so that you don't short-circuit events that you 
-   *  don't handle. In this last case you should return the callee retval.
-   *
-   *  \param[in] event the kind of event received
-   *  \retval 0 if the event was not used or understood
-   *  \retval 1 if the event was used and can be deleted
-   *  \see Fl_Event
+      You normally don't call this method directly, but instead let FLTK do 
+      it when the user interacts with the widget.
+     
+      When implemented in a new widget, this function must return 0 if the 
+      widget does not use the event or 1 otherwise.
+
+      Most of the time, you want to call the inherited handle() method in 
+      your overriden method so that you don't short-circuit events that you 
+      don't handle. In this last case you should return the callee retval.
+    
+      \param[in] event the kind of event received
+      \retval 0 if the event was not used or understood
+      \retval 1 if the event was used and can be deleted
+      \see Fl_Event
    */
   virtual int handle(int event);
 
   /** Returns a pointer to the parent widget.  
-   *  Usually this is a Fl_Group or Fl_Window. 
-   *  \retval NULL if the widget has no parent
-   *  \see Fl_Group::add(Fl_Widget*)
+      Usually this is a Fl_Group or Fl_Window. 
+      \retval NULL if the widget has no parent
+      \see Fl_Group::add(Fl_Widget*)
    */
   Fl_Group* parent() const {return parent_;}
 
-  /** Internal use only. Use Fl_Group::add(Fl_Widget*) instead. */
-  void parent(Fl_Group* p) {parent_ = p;} // for hacks only, Fl_Group::add()
+  /** Internal use only - "for hacks only".
+  
+      It is \em STRONGLY recommended not to use this method, because it
+      short-circuits Fl_Group's normal widget adding and removing methods,
+      if the widget is already a child widget of another Fl_Group.
+
+      Use Fl_Group::add(Fl_Widget*) and/or Fl_Group::remove(Fl_Widget*) instead.
+  */
+  void parent(Fl_Group* p) {parent_ = p;} // for hacks only, use Fl_Group::add()
 
   /** Gets the widget type.
-   *  Returns the widget type value, which is used for Forms
-   *  compatibility and to simulate RTTI.
+      Returns the widget type value, which is used for Forms compatibility
+      and to simulate RTTI.
+      
+      \todo Explain "simulate RTTI" (currently only used to decide if a widget
+      is a window, i.e. type()>=FL_WINDOW ?). Is type() really used in a way
+      that ensures "Forms compatibility" ?
    */
   uchar type() const {return type_;}
 
   /** Sets the widget type.
-   *  This is used for Forms compatibility.
+      This is used for Forms compatibility.
    */
   void type(uchar t) {type_ = t;}
 
   /** Gets the widget position in its window.
-   *  \return the x position relative to the window
+      \return the x position relative to the window
    */
   int x() const {return x_;}
 
   /** Gets the widget position in its window.
-   *  \return the y position relative to the window
+      \return the y position relative to the window
    */
   int y() const {return y_;}
 
   /** Gets the widget width.
-   *  \return the width of the widget in pixels.
+      \return the width of the widget in pixels.
    */
   int w() const {return w_;}
 
   /** Gets the widget height.
-   *  \return the height of the widget in pixels.
+      \return the height of the widget in pixels.
    */
   int h() const {return h_;}
 
-  /** Change the size or position of the widget. 
-   *  This is a virtual function so that the widget may implement its 
-   *  own handling of resizing. The default version does <I>not</I> 
-   *  call the redraw() method, but instead relies on the parent widget 
-   *  to do so because the parent may know a faster way to update the 
-   *  display, such as scrolling from the old position.  
-   *
-   *  Some window managers under X11 call resize() a lot more often 
-   *  than needed. Please verify that the position or size of a widget 
-   *  did actually change before doing any extensive calculations.
-   *
-   *  position(x,y) is a shortcut for resize(x,y,w(),h()), and size(w,h) is a shortcut for resize(x(),y(),w,h).
-   *
-   *  \param[in] x, y new position relative to the parent window 
-   *  \param[in] w, h new size
-   *  \see position(int, int), size(int, int)
+  /** Changes the size or position of the widget.
+
+      This is a virtual function so that the widget may implement its 
+      own handling of resizing. The default version does \e not
+      call the redraw() method, but instead relies on the parent widget 
+      to do so because the parent may know a faster way to update the 
+      display, such as scrolling from the old position.  
+
+      Some window managers under X11 call resize() a lot more often 
+      than needed. Please verify that the position or size of a widget 
+      did actually change before doing any extensive calculations.
+
+      position(X, Y) is a shortcut for resize(X, Y, w(), h()), 
+      and size(W, H) is a shortcut for resize(x(), y(), W, H).
+    
+      \param[in] x, y new position relative to the parent window 
+      \param[in] w, h new size
+      \see position(int,int), size(int,int)
    */
   virtual void resize(int x, int y, int w, int h);
 
   /** Internal use only. */
   int damage_resize(int,int,int,int);
 
-  /** Reposition the window or widget.
-   *  position(X,Y) is a shortcut for resize(X,Y,w(),h()).
-   *
-   *  \param[in] X, Y new position relative to the parent window 
-   *  \see resize(int, int, int, int), size(int, int)
+  /** Repositions the window or widget.
+      position(X, Y) is a shortcut for resize(X, Y, w(), h()).
+    
+      \param[in] X, Y new position relative to the parent window 
+      \see resize(int,int,int,int), size(int,int)
    */
   void position(int X,int Y) {resize(X,Y,w_,h_);}
 
   /** Change the size of the widget.
-   *  size(w,h) is a shortcut for resize(x(),y(),w,h).
-   *
-   *  \param[in] W, H new size
-   *  \see position(int, int), resize(int, int, int, int)
+      size(W, H) is a shortcut for resize(x(), y(), W, H).
+    
+      \param[in] W, H new size
+      \see position(int,int), resize(int,int,int,int)
    */
   void size(int W,int H) {resize(x_,y_,W,H);}
 
   /** Gets the label alignment.
-   *  \return label alignment
-   *  \see label(), align(Fl_Align), Fl_Align
-   *  \todo This function should not take uchar as an argument. Apart from the fact that uchar is too short 
-   *        with only 8 bits, it does not provide type safety (in which case we don't need to declare Fl_Type
-   *        an enum to begin with).
+      \return label alignment
+      \see label(), align(Fl_Align), Fl_Align
+      \todo This function should not take uchar as an argument. 
+            Apart from the fact that uchar is too short with only 8 bits, 
+	    it does not provide type safety (in which case we don't need 
+	    to declare Fl_Align an enum to begin with).
+	    *NOTE* The current (FLTK 1.3) implementation (Dec 2008) is such that
+	    Fl_Align is (typedef'd to be) "unsigned" (int), but Fl_Widget's
+	    "align_" member variable is a bit field of 8 bits only !
    */
   Fl_Align align() const {return align_;}
 
   /** Sets the label alignment.
-   * This controls how the label is displayed next to or inside the widget. 
-   * The default value is FL_ALIGN_CENTER, which centers the label inside the widget.
-   * \param[in] alignment new label alignment
-   * \see align(), Fl_Align
+      This controls how the label is displayed next to or inside the widget. 
+      The default value is FL_ALIGN_CENTER, which centers the label inside 
+      the widget.
+      \param[in] alignment new label alignment
+      \see align(), Fl_Align
    */
   void align(Fl_Align alignment) {align_ = alignment;}
 
-  /** Gets the box type for the widget.
-   *  \return the current box type
-   *  \see box(Fl_Boxtype), Fl_Boxtype
+  /** Gets the box type of the widget.
+      \return the current box type
+      \see box(Fl_Boxtype), Fl_Boxtype
    */
   Fl_Boxtype box() const {return (Fl_Boxtype)box_;}
   
   /** Sets the box type for the widget. 
-   *  This identifies a routine that draws the background of the widget. 
-   *  See Fl_Boxtype for the available types. The default depends on the widget, 
-   *  but is usually FL_NO_BOX or FL_UP_BOX.
-   *  \param[in] new_box the new box type
-   *  \see box(), Fl_Boxtype
+      This identifies a routine that draws the background of the widget.
+      See Fl_Boxtype for the available types. The default depends on the 
+      widget, but is usually FL_NO_BOX or FL_UP_BOX.
+      \param[in] new_box the new box type
+      \see box(), Fl_Boxtype
    */
   void box(Fl_Boxtype new_box) {box_ = new_box;}
 
   /** Gets the background color of the widget.
-   *  \return current background color
-   *  \see color(unsigned), color(unsigned, unsigned)
+      \return current background color
+      \see color(unsigned), color(unsigned, unsigned)
    */
   Fl_Color color() const {return (Fl_Color)color_;}
 
   /** Sets the background color of the widget. 
-   *  The color is passed to the box routine. The color is either an index into an 
-   *  internal table of RGB colors or an RGB color value generated using fl_rgb_color().
-   *  The default for most widgets is FL_BACKGROUND_COLOR. Use Fl::set_color() to 
-   *  redefine colors in the color map.
-   *  \param[in] bg background color
-   *  \see color(), color(unsigned, unsigned), selection_color(unsigned)
+      The color is passed to the box routine. The color is either an index into 
+      an internal table of RGB colors or an RGB color value generated using 
+      fl_rgb_color().
+      
+      The default for most widgets is FL_BACKGROUND_COLOR. Use Fl::set_color()
+      to redefine colors in the color map.
+      \param[in] bg background color
+      \see color(), color(unsigned, unsigned), selection_color(unsigned)
    */
   void color(unsigned bg) {color_ = bg;}
 
   /** Gets the selection color.
-   *  \return the current selection color
-   *  \see selection_color(unsigned), color(unsigned, unsigned)
+      \return the current selection color
+      \see selection_color(unsigned), color(unsigned, unsigned)
    */
   Fl_Color selection_color() const {return (Fl_Color)color2_;}
 
-  /** Gets or sets the selection color.
-   *  The selection color is defined for Forms compatibility and is usually 
-   *  used to color the widget when it is selected, although some widgets 
-   *  use this color for other purposes. You can set both colors at once 
-   *  with color(int, int).
-   *  \param[in] a the new selection color
-   *  \see selection_color(), color(unsigned, unsigned)
+  /** Sets the selection color.
+      The selection color is defined for Forms compatibility and is usually 
+      used to color the widget when it is selected, although some widgets 
+      use this color for other purposes. You can set both colors at once 
+      with color(unsigned bg, unsigned sel).
+      \param[in] a the new selection color
+      \see selection_color(), color(unsigned, unsigned)
    */
   void selection_color(unsigned a) {color2_ = a;}
 
   /** Sets the background and selection color of the widget. 
-   *  The two color form sets both the background and selection colors. 
-   *  \param[in] bg background color
-   *  \param[in] sel selection color
-   *  \see color(unsigned), selection_color(unsigned)
+
+      The two color form sets both the background and selection colors. 
+      \param[in] bg background color
+      \param[in] sel selection color
+      \see color(unsigned), selection_color(unsigned)
    */
   void color(unsigned bg, unsigned sel) {color_=bg; color2_=sel;}
 
   /** Get the current label text.
-   *  \return a pointer to the current label text
-   *  \see label(Fl_CString), copy_label(Fl_CString)
+      \return a pointer to the current label text
+      \see label(Fl_CString), copy_label(Fl_CString)
    */
   const char* label() const {return label_.value;}
 
-  /** Get or set the current label pointer. 
-   *  The label is shown somewhere on or next to the widget. The passed pointer 
-   *  is stored unchanged in the widget (the string is \em not copied), so if 
-   *  you need to set the label to a formatted value, make sure the buffer is 
-   *  static, global, or allocated. The copy_label() method can be used 
-   *  to make a copy of the label string automatically.
-   *  \param[in] text pointer to new label text
-   *  \see copy_label()
+  /** Sets the current label pointer.
+
+      The label is shown somewhere on or next to the widget. The passed pointer 
+      is stored unchanged in the widget (the string is \em not copied), so if 
+      you need to set the label to a formatted value, make sure the buffer is 
+      static, global, or allocated. The copy_label() method can be used 
+      to make a copy of the label string automatically.
+      \param[in] text pointer to new label text
+      \see copy_label()
    */
   void label(const char* text);
 
   /** Sets the current label. 
-   *  Unlike label(), this method allocates a copy of the label 
-   *  string instead of using the original string pointer.
-   *  \param[in] new_label the new label text
-   *  \see label()
+      Unlike label(), this method allocates a copy of the label 
+      string instead of using the original string pointer.
+      \param[in] new_label the new label text
+      \see label()
    */
   void copy_label(Fl_CString new_label);
 
   /** Shortcut to set the label text and type in one call.
-   *  \see label(FL_CString), labeltype(Fl_Labeltype)
+      \see label(FL_CString), labeltype(Fl_Labeltype)
    */
-  void label(Fl_Labeltype a,const char* b) {label_.type = a; label_.value = b;}
+  void label(Fl_Labeltype a, const char* b) {label_.type = a; label_.value = b;}
 
   /** Gets the label type.
-   *  \return the current label type.
-   *  \see Fl_Labeltype
+      \return the current label type.
+      \see Fl_Labeltype
    */
   Fl_Labeltype labeltype() const {return (Fl_Labeltype)label_.type;}
 
   /** Sets the label type. 
-   *  The label type identifies the function that draws the label of the widget. 
-   *  This is generally used for special effects such as embossing or for using 
-   *  the label() pointer as another form of data such as an icon. The value 
-   *  FL_NORMAL_LABEL prints the label as plain text.
-   *  \param[in] a new label type
-   *  \see Fl_Labeltype
+      The label type identifies the function that draws the label of the widget. 
+      This is generally used for special effects such as embossing or for using 
+      the label() pointer as another form of data such as an icon. The value 
+      FL_NORMAL_LABEL prints the label as plain text.
+      \param[in] a new label type
+      \see Fl_Labeltype
    */
   void labeltype(Fl_Labeltype a) {label_.type = a;}
 
   /** Gets the label color. 
-   *  The default color is FL_FOREGROUND_COLOR. 
-   *  \return the current label color
+      The default color is FL_FOREGROUND_COLOR. 
+      \return the current label color
    */
   Fl_Color labelcolor() const {return (Fl_Color)label_.color;}
 
   /** Sets the label color. 
-   *  The default color is FL_FOREGROUND_COLOR. 
-   *  \param[in] c the new label color
+      The default color is FL_FOREGROUND_COLOR. 
+      \param[in] c the new label color
    */
   void labelcolor(unsigned c) {label_.color=c;}
 
   /** Gets the font to use. 
-   *  Fonts are identified by indexes into a table. The default value uses a 
-   *  Helvetica typeface (Arial for Microsoft&reg; Windows&reg;). The function 
-   *  Fl::set_font() can define new typefaces.
-   *  \return current font used by the label
-   *  \see Fl_Font
+      Fonts are identified by indexes into a table. The default value uses a 
+      Helvetica typeface (Arial for Microsoft&reg; Windows&reg;). The function 
+      Fl::set_font() can define new typefaces.
+      \return current font used by the label
+      \see Fl_Font
    */
   Fl_Font labelfont() const {return label_.font;}
 
   /** Sets the font to use. 
-   *  Fonts are identified by indexes into a table. The default value uses a 
-   *  Helvetica typeface (Arial for Microsoft&reg; Windows&reg;). The function 
-   *  Fl::set_font() can define new typefaces.
-   *  \param[in] f the new font for the label
-   *  \see Fl_Font
+      Fonts are identified by indexes into a table. The default value uses a 
+      Helvetica typeface (Arial for Microsoft&reg; Windows&reg;). The 
+      function Fl::set_font() can define new typefaces.
+      \param[in] f the new font for the label
+      \see Fl_Font
    */
   void labelfont(Fl_Font f) {label_.font=f;}
 
   /** Gets the font size in pixels. 
-   *  The default size is 14 pixels.
-   *  \return the current font size
+      The default size is 14 pixels.
+      \return the current font size
    */
   Fl_Fontsize labelsize() const {return label_.size;}
 
-  /** Gets or sets the font size in pixels. 
-   *  The default size is 14 pixels.
-   *  \param[in] pix the new font size
+  /** Sets the font size in pixels.
+      \param[in] pix the new font size
+      \see Fl_Fontsize labelsize()
    */
   void labelsize(Fl_Fontsize pix) {label_.size=pix;}
 
-  /** Gets or sets the image to use as part of the widget label.
-   *  This image is used when drawing the widget in the active state.
-   *  \return the current image
+  /** Gets the image that is used as part of the widget label.
+      This image is used when drawing the widget in the active state.
+      \return the current image
    */
   Fl_Image* image() {return label_.image;}
 
-  /** Gets or sets the image to use as part of the widget label.
-   *  This image is used when drawing the widget in the active state.
-   *  \param[in] img the new image for the label 
+  /** Sets the image to use as part of the widget label.
+      This image is used when drawing the widget in the active state.
+      \param[in] img the new image for the label 
    */
   void image(Fl_Image* img) {label_.image=img;}
 
-  /** Gets or sets the image to use as part of the widget label.
-   *  This image is used when drawing the widget in the active state.
-   *  \param[in] img the new image for the label 
+  /** Sets the image to use as part of the widget label.
+      This image is used when drawing the widget in the active state.
+      \param[in] img the new image for the label 
    */
   void image(Fl_Image& img) {label_.image=&img;}
 
-  /** Gets the image to use as part of the widget label.  
-   *  This image is used when drawing the widget in the inactive state.
-   *  \return the current deactivated image for this widget
+  /** Gets the image that is used as part of the widget label.  
+      This image is used when drawing the widget in the inactive state.
+      \return the current image for the deactivated widget
    */
   Fl_Image* deimage() {return label_.deimage;}
 
   /** Sets the image to use as part of the widget label.  
-   *  This image is used when drawing the widget in the inactive state.
-   *  \param[in] img the new image for the deactivated widget
+      This image is used when drawing the widget in the inactive state.
+      \param[in] img the new image for the deactivated widget
    */
   void deimage(Fl_Image* img) {label_.deimage=img;}
 
   /** Sets the image to use as part of the widget label.  
-   *  This image is used when drawing the widget in the inactive state.
-   *  \param[in] img the new image for the deactivated widget
+      This image is used when drawing the widget in the inactive state.
+      \param[in] img the new image for the deactivated widget
    */
   void deimage(Fl_Image& img) {label_.deimage=&img;}
 
   /** Gets the current tooltip text.
-   *  \return a pointer to the tooltip text or NULL
+      \return a pointer to the tooltip text or NULL
    */
   const char *tooltip() const {return tooltip_;}
 
   /** Sets the current tooltip text. 
-   *  Sets a string of text to display in a popup tooltip window when the user 
-   *  hovers the mouse over the widget. The string is <I>not</I> copied, so 
-   *  make sure any formatted string is stored in a static, global, 
-   *  or allocated buffer.
-   * 
-   *  If no tooltip is set, the tooltip of the parent is inherited. Setting a 
-   *  tooltip for a group and setting no tooltip for a child will show the 
-   *  group's tooltip instead. To avoid this behavior, you can set the child's 
-   *  tooltip to an empty string ("").
-   *  \param[in] t new tooltip
+      Sets a string of text to display in a popup tooltip window when the user 
+      hovers the mouse over the widget. The string is <I>not</I> copied, so 
+      make sure any formatted string is stored in a static, global, 
+      or allocated buffer.
+     
+      If no tooltip is set, the tooltip of the parent is inherited. Setting a 
+      tooltip for a group and setting no tooltip for a child will show the 
+      group's tooltip instead. To avoid this behavior, you can set the child's 
+      tooltip to an empty string ("").
+      \param[in] t new tooltip
    */
   void tooltip(const char *t);
 
   /** Gets the current callback function for the widget.
-   *  Each widget has a single callback.
-   *  \return current callback
+      Each widget has a single callback.
+      \return current callback
    */
   Fl_Callback_p callback() const {return callback_;}
 
   /** Sets the current callback function for the widget.
-   *  Each widget has a single callback.
-   *  \param[in] cb new callback
-   *  \param[in] p user data
+      Each widget has a single callback.
+      \param[in] cb new callback
+      \param[in] p user data
    */
   void callback(Fl_Callback* cb, void* p) {callback_=cb; user_data_=p;}
 
   /** Sets the current callback function for the widget.
-   *  Each widget has a single callback.
-   *  \param[in] cb new callback
+      Each widget has a single callback.
+      \param[in] cb new callback
    */
   void callback(Fl_Callback* cb) {callback_=cb;}
 
   /** Sets the current callback function for the widget.
-   *  Each widget has a single callback.
-   *  \param[in] cb new callback
+      Each widget has a single callback.
+      \param[in] cb new callback
    */
   void callback(Fl_Callback0*cb) {callback_=(Fl_Callback*)cb;}
 
   /** Sets the current callback function for the widget.
-   *  Each widget has a single callback.
-   *  \param[in] cb new callback
-   *  \param[in] p user data
+      Each widget has a single callback.
+      \param[in] cb new callback
+      \param[in] p user data
    */
   void callback(Fl_Callback1*cb, long p=0) {callback_=(Fl_Callback*)cb; user_data_=(void*)p;}
 
   /** Gets the user data for this widget.
-   *  Gets the current user data (void *) argument
-   *  that is passed to the callback function.
-   *  \return user data as a pointer
+      Gets the current user data (void *) argument
+      that is passed to the callback function.
+      \return user data as a pointer
    */
   void* user_data() const {return user_data_;}
 
   /** Sets the user data for this widget.
-   *  Sets the new user data (void *) argument
-   *  that is passed to the callback function.
-   *  \param[in] v new user data
+      Sets the new user data (void *) argument
+      that is passed to the callback function.
+      \param[in] v new user data
    */
   void user_data(void* v) {user_data_ = v;}
 
@@ -542,259 +566,254 @@ public:
   long argument() const {return (long)user_data_;}
 
   /** Sets the current user data (long) argument that is passed to the callback function.
-   *  \todo The user data value must be implemented using a \em union to avoid 64 bit machine incompatibilities.
+      \todo The user data value must be implemented using a \em union to avoid 
+      64 bit machine incompatibilities.
    */
   void argument(long v) {user_data_ = (void*)v;}
 
-  /**
-     Controls when callbacks are done. The following values are useful,
-     the default value is FL_WHEN_RELEASE:
-  
-  <UL>
-  
-  	<LI>0: The callback is not done, but
-  	changed() is turned on.</LI>
-  
-  	<LI>FL_WHEN_CHANGED: The callback is done each
-  	time the text is changed by the user.</LI>
-  
-  	<LI>FL_WHEN_RELEASE: The callback will be done
-  	when this widget loses the focus, including when the
-  	window is unmapped. This is a useful value for text
-  	fields in a panel where doing the callback on every
-  	change is wasteful. However the callback will also
-  	happen if the mouse is moved out of the window, which
-  	means it should not do anything visible (like pop up an
-  	error message). You might do better setting this to
-  	zero, and scanning all the items for changed()
-  	when the OK button on a panel is pressed.</LI>
-  
-  	<LI>FL_WHEN_ENTER_KEY: If the user types the
-  	Enter key, the entire text is selected, and the callback
-  	is done if the text has changed. Normally the Enter key
-  	will navigate to the next field (or insert a newline for
-  	a Fl_Mulitline_Input), this changes the
-  	behavior.</LI>
-  
-  	<LI>FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The
-  	Enter key will do the callback even if the text has not
-  	changed. Useful for command fields.</LI>
-  
-  </UL>
-	Return the conditions under which the callback is called.
-        \return set of flags
+  /** Returns the conditions under which the callback is called.
+
+      You can set the flags with when(uchar), the default value is
+      FL_WHEN_RELEASE.
+
+      \return set of flags
+      \see when(uchar)
    */
   Fl_When when() const {return (Fl_When)when_;}
 
-  /** Flags used to decide when a callback is called.
-   *  Fl_Widget::when() is a set of bitflags used by subclasses of 
-   *   Fl_Widget to decide when to do the callback.  If the value 
-   *  is zero then the callback is never done.  Other values are described 
-   *  in the individual widgets.  This field is in the base class so that 
-   *  you can scan a panel and do_callback() on all the ones that 
-   *  don't do their own callbacks in response to an "OK" button.
-   *  \param[in] i set of flags 
+  /** Sets the flags used to decide when a callback is called.
+
+     This controls when callbacks are done. The following values are useful,
+     the default value is FL_WHEN_RELEASE:
+     
+     \li 0: The callback is not done, but changed() is turned on.
+     \li FL_WHEN_CHANGED: The callback is done each time the text is
+         changed by the user.</LI>
+     \li FL_WHEN_RELEASE: The callback will be done when this widget loses 
+         the focus, including when the window is unmapped. This is a useful 
+	 value for text fields in a panel where doing the callback on every
+  	 change is wasteful. However the callback will also happen if the 
+	 mouse is moved out of the window, which means it should not do 
+	 anything visible (like pop up an error message).
+	 You might do better setting this to zero, and scanning all the
+	 items for changed() when the OK button on a panel is pressed.
+     \li FL_WHEN_ENTER_KEY: If the user types the Enter key, the entire 
+         text is selected, and the callback is done if the text has changed. 
+	 Normally the Enter key will navigate to the next field (or insert 
+	 a newline for a Fl_Mulitline_Input) - this changes the behavior.
+     \li FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The Enter key will do the
+         callback even if the text has not changed. Useful for command fields.
+      Fl_Widget::when() is a set of bitflags used by subclasses of 
+      Fl_Widget to decide when to do the callback.
+
+      If the value is zero then the callback is never done. Other values 
+      are described  in the individual widgets. This field is in the base 
+      class so that you can scan a panel and do_callback() on all the ones
+      that don't do their own callbacks in response to an "OK" button.
+      \param[in] i set of flags
    */
   void when(uchar i) {when_ = i;}
 
-  /** Returns whether a widget is visble.
-   *  \retval 0 if the widget is not drawn and hence invisible.
-   *  \see show(), hide(), visible_r()
+  /** Returns whether a widget is visible.
+      \retval 0 if the widget is not drawn and hence invisible.
+      \see show(), hide(), visible_r()
    */
   int visible() const {return !(flags_&INVISIBLE);}
   
   /** Returns whether a widget and all its parents are visible.
-   *  \retval 0 if the widget or any of its parents are invisible.
-   *  \see show(), hide(), visible()
+      \retval 0 if the widget or any of its parents are invisible.
+      \see show(), hide(), visible()
    */
   int visible_r() const;
 
   /** Makes a widget visible.
-   *  An invisible widget never gets redrawn and does not get events.  
-   *  The visible() method returns true if the widget is set to be  
-   *  visible. The visible_r() method returns true if the widget and 
-   *  all of its parents are visible. A widget is only visible if 
-   *  visible() is true on it <I>and all of its parents</I>. 
-   * 
-   *  Changing it will send FL_SHOW or FL_HIDE events to 
-   *  the widget. <I>Do not change it if the parent is not visible, as this 
-   *  will send false FL_SHOW or FL_HIDE events to the 
-   *  widget</I>. redraw() is called if necessary on this or the parent.
-   *  
-   *  \see hide(), visible(), visible_r()
+      An invisible widget never gets redrawn and does not get events.  
+      The visible() method returns true if the widget is set to be  
+      visible. The visible_r() method returns true if the widget and 
+      all of its parents are visible. A widget is only visible if 
+      visible() is true on it <I>and all of its parents</I>. 
+
+      Changing it will send FL_SHOW or FL_HIDE events to 
+      the widget. <I>Do not change it if the parent is not visible, as this 
+      will send false FL_SHOW or FL_HIDE events to the widget</I>.
+      redraw() is called if necessary on this or the parent.
+
+      \see hide(), visible(), visible_r()
    */
   virtual void show();
   
   /** Makes a widget invisible.
-   *  \see show(), visible(), visible_r()
+      \see show(), visible(), visible_r()
    */
   virtual void hide();
 
   /** Makes the widget visible. 
-   *  You must still redraw the parent widget to see a change in the 
-   *  window. Normally you want to use the show() method instead.
+      You must still redraw the parent widget to see a change in the 
+      window. Normally you want to use the show() method instead.
    */
   void set_visible() {flags_ &= ~INVISIBLE;}
 
   /** Hides the widget. 
-   *  You must still redraw the parent to see a change in the window. 
-   *  Normally you want to use the hide() method instead.
+      You must still redraw the parent to see a change in the window. 
+      Normally you want to use the hide() method instead.
    */
   void clear_visible() {flags_ |= INVISIBLE;}
 
   /** Returns whether the widget is active.
-   *  \retval 0 if the widget is inactive
-   *  \see active_r(), activate(), deactivate()
+      \retval 0 if the widget is inactive
+      \see active_r(), activate(), deactivate()
    */
   int active() const {return !(flags_&INACTIVE);}
 
-  /** active_r() returns whether the widget and all of its 
-   *  parents are active. 
-   *  \retval 0 if this or any of the parent widgets are inactive
-   *  \see active(), activate(), deactivate()
+  /** Returns whether the widget and all of its parents are active. 
+      \retval 0 if this or any of the parent widgets are inactive
+      \see active(), activate(), deactivate()
    */
   int active_r() const;
 
-  /** Activate a widget.
-   *  Changing this value will send FL_ACTIVATE to the widget if 
-   *  active_r() is true.
-   *  \see active(), active_r(), deactivate()
+  /** Activates the widget.
+      Changing this value will send FL_ACTIVATE to the widget if 
+      active_r() is true.
+      \see active(), active_r(), deactivate()
    */
   void activate();
 
-  /** Deactivate a widget.
-   *  Inactive widgets will be drawn "grayed out", e.g. with less contrast 
-   *  than the active widget. Inactive widgets will not receive any keyboard 
-   *  or mouse button events. Other events (including FL_ENTER, FL_MOVE, 
-   *  FL_LEAVE, FL_SHORTCUT, and others) will still be sent. A widget is 
-   *  only active if active() is true on it <I>and all of its parents</I>.  
-   *
-   *  Changing this value will send FL_DEACTIVATE to the widget if 
-   *  active_r() is true.
-   *
-   *  Currently you cannot deactivate Fl_Window widgets.
-   *
-   *  \see activate(), active(), active_r()
+  /** Deactivates the widget.
+      Inactive widgets will be drawn "grayed out", e.g. with less contrast 
+      than the active widget. Inactive widgets will not receive any keyboard 
+      or mouse button events. Other events (including FL_ENTER, FL_MOVE, 
+      FL_LEAVE, FL_SHORTCUT, and others) will still be sent. A widget is 
+      only active if active() is true on it <I>and all of its parents</I>.  
+
+      Changing this value will send FL_DEACTIVATE to the widget if 
+      active_r() is true.
+    
+      Currently you cannot deactivate Fl_Window widgets.
+
+      \see activate(), active(), active_r()
    */
   void deactivate();
 
-  /** Return if a widget is used for output only.
-   *  output() means the same as !active() except it does not change how the 
-   *  widget is drawn. The widget will not receive any events. This is useful 
-   *  for making scrollbars or buttons that work as displays rather than input devices.
-   *  \retval 0 if the widget is used for input and output
-   *  \see set_output(), clear_output() 
+  /** Returns if a widget is used for output only.
+      output() means the same as !active() except it does not change how the 
+      widget is drawn. The widget will not receive any events. This is useful 
+      for making scrollbars or buttons that work as displays rather than input 
+      devices.
+      \retval 0 if the widget is used for input and output
+      \see set_output(), clear_output() 
    */
   int output() const {return (flags_&OUTPUT);}
 
-  /** Set a widget to output only.
-   *  \see output(), clear_output() 
+  /** Sets a widget to output only.
+      \see output(), clear_output() 
    */
   void set_output() {flags_ |= OUTPUT;}
 
-  /** Set a widget to accept input.
-   *  \see set_output(), output() 
+  /** Sets a widget to accept input.
+      \see set_output(), output() 
    */
   void clear_output() {flags_ &= ~OUTPUT;}
 
   /** Returns if the widget is able to take events.
-   *  This is the same as (active() && !output()
-   *  && visible()) but is faster.
-   *  \retval 0 if the widget takes no events
+      This is the same as (active() && !output()
+      && visible()) but is faster.
+      \retval 0 if the widget takes no events
    */ 
   int takesevents() const {return !(flags_&(INACTIVE|INVISIBLE|OUTPUT));}
 
   /** 
-   *  Check if the widget value changed since the last callback.
-   *  "Changed" is a flag that is turned on when the user changes the value stored 
-   *  in the widget. This is only used by subclasses of Fl_Widget that store values, 
-   *  but is in the base class so it is easier to scan all the widgets in a panel 
-   *  and do_callback() on the changed ones in response to an "OK" button.
-   *
-   *  Most widgets turn this flag off when they do the callback, and when the program 
-   *  sets the stored value.
-   *
-   * \retval 0 if the value did not change
-   * \see set_changed(), clear_changed()`
+      Check if the widget value changed since the last callback.
+
+      "Changed" is a flag that is turned on when the user changes the value 
+      stored in the widget. This is only used by subclasses of Fl_Widget that 
+      store values, but is in the base class so it is easier to scan all the 
+      widgets in a panel and do_callback() on the changed ones in response 
+      to an "OK" button.
+
+      Most widgets turn this flag off when they do the callback, and when 
+      the program sets the stored value.
+
+     \retval 0 if the value did not change
+     \see set_changed(), clear_changed()
    */
   int changed() const {return flags_&CHANGED;}
 
-  /** Mark the value of the widget as changed.
-   *  \see changed(), clear_changed()
+  /** Marks the value of the widget as changed.
+      \see changed(), clear_changed()
    */
   void set_changed() {flags_ |= CHANGED;}
 
-  /** Mark the value of the widget as unchanged.
-   *  \see changed(), set_changed()
+  /** Marks the value of the widget as unchanged.
+      \see changed(), set_changed()
    */
   void clear_changed() {flags_ &= ~CHANGED;}
 
-  /** Give the widget the keyboard focus.
-   *  Tries to make this widget be the Fl::focus() widget, by first sending 
-   *  it an FL_FOCUS event, and if it returns non-zero, setting 
-   *  Fl::focus() to this widget.  You should use this method to 
-   *  assign the focus to a widget.  
-   *  \return true if the widget accepted the focus.
+  /** Gives the widget the keyboard focus.
+      Tries to make this widget be the Fl::focus() widget, by first sending 
+      it an FL_FOCUS event, and if it returns non-zero, setting 
+      Fl::focus() to this widget. You should use this method to 
+      assign the focus to a widget.  
+      \return true if the widget accepted the focus.
    */
   int take_focus();
 
   /** Enables keyboard focus navigation with this widget. 
-   *  Note, however, that this will not necessarily mean that the widget will 
-   *  accept focus, but for widgets that can accept focus, this method enables 
-   *  it if it has been disabled.
-   *  \see visible_focus(), clear_visible_focus(), visible_focus(int) 
+      Note, however, that this will not necessarily mean that the widget will 
+      accept focus, but for widgets that can accept focus, this method enables 
+      it if it has been disabled.
+      \see visible_focus(), clear_visible_focus(), visible_focus(int) 
    */
   void set_visible_focus() { flags_ |= VISIBLE_FOCUS; }
 
   /** Disables keyboard focus navigation with this widget. 
-   *  Normally, all widgets participate in keyboard focus navigation.
-   *  \see set_visible_focus(), visible_focus(), visible_focus(int) 
+      Normally, all widgets participate in keyboard focus navigation.
+      \see set_visible_focus(), visible_focus(), visible_focus(int) 
    */
   void clear_visible_focus() { flags_ &= ~VISIBLE_FOCUS; }
 
   /** Modifies keyboard focus navigation. 
-   *  \param[in] v set or clear visible focus
-   *  \see set_visible_focus(), clear_visible_focus(), visible_focus() 
+      \param[in] v set or clear visible focus
+      \see set_visible_focus(), clear_visible_focus(), visible_focus() 
    */
   void visible_focus(int v) { if (v) set_visible_focus(); else clear_visible_focus(); }
  
   /** Check whether this widget has a visible focus.
-   *  \retval 0 if this widget has no visible focus.
-   *  \see visible_focus(int), set_visible_focus(), clear_visible_focus()
+      \retval 0 if this widget has no visible focus.
+      \see visible_focus(int), set_visible_focus(), clear_visible_focus()
    */
   int  visible_focus() { return flags_ & VISIBLE_FOCUS; }
 
   /** Sets the default callback for all widgets.
-   *  Sets the default callback, which puts a pointer to the widget on the queue 
-   *  returned by Fl::readqueue(). You may want to call this from your own callback.
-   *  \param[in] cb the new callback
-   *  \param[in] d user data associated with that callback
-   *  \see callback(), do_callback(), Fl::readqueu()
+      Sets the default callback, which puts a pointer to the widget on the queue 
+      returned by Fl::readqueue(). You may want to call this from your own callback.
+      \param[in] cb the new callback
+      \param[in] d user data associated with that callback
+      \see callback(), do_callback(), Fl::readqueu()
    */
   static void default_callback(Fl_Widget *cb, void *d);
 
-  /** Call the widget callback.
-   *  Causes a widget to invoke its callback function, optionally
-   *  with arbitrary arguments.
-   *  \see callback()
+  /** Calls the widget callback.
+      Causes a widget to invoke its callback function, optionally
+      with arbitrary arguments.
+      \see callback()
    */
   void do_callback() {callback_(this,user_data_); if (callback_ != default_callback) clear_changed();}
 
-  /** Call the widget callback.
-   *  Causes a widget to invoke its callback function, optionally
-   *  with arbitrary arguments.
-   *  \param[in] o call the callback with \em o as the widget argument
-   *  \param[in] arg call the callback with \em arg as the user data argument
-   *  \see callback()
+  /** Calls the widget callback.
+      Causes a widget to invoke its callback function, optionally
+      with arbitrary arguments.
+      \param[in] o call the callback with \em o as the widget argument
+      \param[in] arg call the callback with \em arg as the user data argument
+      \see callback()
    */
   void do_callback(Fl_Widget* o,void* arg=0) {callback_(o,arg); if (callback_ != default_callback) clear_changed();}
 
-  /** Call the widget callback.
-   *  Causes a widget to invoke its callback function, optionally
-   *  with arbitrary arguments.
-   *  \param[in] o call the callback with \em o as the widget argument
-   *  \param[in] arg call the callback with \em arg as the user data argument
-   *  \see callback()
+  /** Calls the widget callback.
+      Causes a widget to invoke its callback function, optionally
+      with arbitrary arguments.
+      \param[in] o call the callback with \em o as the widget argument
+      \param[in] arg call the callback with \em arg as the user data argument
+      \see callback()
    */
   void do_callback(Fl_Widget* o,long arg) {callback_(o,(void*)arg); if (callback_ != default_callback) clear_changed();}
 
@@ -806,73 +825,83 @@ public:
   static int test_shortcut(const char*);
 
   /** Checks if w is a child of this widget.
-   *  \param[in] w potential child widget
-   *  \return Returns 1 if \em w is a child of this widget, or is
-   *  equal to this widget. Returns 0 if \em w is NULL.
+      \param[in] w potential child widget
+      \return Returns 1 if \em w is a child of this widget, or is
+      equal to this widget. Returns 0 if \em w is NULL.
    */
   int contains(const Fl_Widget *w) const ;
 
-  /** Check if this widget is a child of w.
-   *  Returns 1 if this widget is a child of \em w, or is
-   *  equal to \em w. Returns 0 if \em w is NULL.
-   *  \param[in] w the possible parent widget.
-   *  \see contains()
+  /** Checks if this widget is a child of w.
+      Returns 1 if this widget is a child of \em w, or is
+      equal to \em w. Returns 0 if \em w is NULL.
+      \param[in] w the possible parent widget.
+      \see contains()
    */
   int inside(const Fl_Widget* w) const {return w ? w->contains(this) : 0;}
 
-  /** Schedule the drawing of the widget.
-   *  Marks the widget as needing its draw() routine called.
+  /** Schedules the drawing of the widget.
+      Marks the widget as needing its draw() routine called.
    */
   void redraw();
 
-  /** Schedule the drawing of the label.
-   * Marks the widget or the parent as needing a redraw for the label area of a widget.
+  /** Schedules the drawing of the label.
+     Marks the widget or the parent as needing a redraw for the label area 
+     of a widget.
    */
   void redraw_label();
 
   /** Returns non-zero if draw() needs to be called. 
-   *  The damage value is actually a bit field that the widget 
-   *  subclass can use to figure out what parts to draw.
-   *  \return a bitmap of flags describing the kind of damage to the widget
-   *  \see damage(uchar), clear_damage(uchar)
+      The damage value is actually a bit field that the widget 
+      subclass can use to figure out what parts to draw.
+      \return a bitmap of flags describing the kind of damage to the widget
+      \see damage(uchar), clear_damage(uchar)
    */
   uchar damage() const {return damage_;}
 
-  /** Clear damage flags.
-   *  Damage flags are cleared when parts of the widget drawing is repaired.
-   *  \param[in] c bitmask of flags to clear
-   *  \see damage(uchar), damage()
+  /** Clears the damage flags.
+      Damage flags are cleared when parts of the widget drawing is repaired.
+      \param[in] c bitmask of flags to clear
+      \see damage(uchar), damage()
    */
   void clear_damage(uchar c = 0) {damage_ = c;}
 
-  /** Set the damage bits for the widget.
-   *  Setting damage bits will schedule the widget for the next redraw.
-   *  \param[in] c bitmask of flags to set
-   *  \see damage(), clear_damage(uchar)
+  /** Sets the damage bits for the widget.
+      Setting damage bits will schedule the widget for the next redraw.
+      \param[in] c bitmask of flags to set
+      \see damage(), clear_damage(uchar)
    */
   void damage(uchar c);
 
-  /** Set the damage bits for an area inside the widget.
-   *  Setting damage bits will schedule the widget for the next redraw.
-   *  \param[in] c bitmask of flags to set
-   *  \param[in] x, y, w, h size of damaged area
-   *  \see damage(), clear_damage(uchar)
+  /** Sets the damage bits for an area inside the widget.
+      Setting damage bits will schedule the widget for the next redraw.
+      \param[in] c bitmask of flags to set
+      \param[in] x, y, w, h size of damaged area
+      \see damage(), clear_damage(uchar)
    */
   void damage(uchar c, int x, int y, int w, int h);
 
   void draw_label(int, int, int, int, Fl_Align) const;
-  /** Sets width ww, height hh accordingly with the labeltype size, label with images will return w() h() of the image. */
+
+  /** Sets width ww and height hh accordingly with the labeltype size.
+      Labels with images will return w() and h() of the image.
+   */
   void measure_label(int& ww, int& hh) {label_.measure(ww, hh);}
 
   /** Returns a pointer to the primary Fl_Window widget.
-   *  \retval  NULL if no window is associated with this widget.  
-   *  \note for an Fl_Window widget, this returns its <I>parent</I> window (if any), not <I>this</I> window.
+      \retval  NULL if no window is associated with this widget.  
+      \note for an Fl_Window widget, this returns its <I>parent</I> window 
+            (if any), not <I>this</I> window.
    */
   Fl_Window* window() const ;
 
-  /** For back compatibility only. */
+  /** For back compatibility only.
+      \deprecated Use selection_color() instead.
+  */
   Fl_Color color2() const {return (Fl_Color)color2_;}
-  /** For back compatibility only. */
+
+  /** For back compatibility only.
+      \deprecated Use selection_color(unsigned) instead.
+  */
   void color2(unsigned a) {color2_ = a;}
 };