Doxygen documentation WP8 Done. Reserved WP9, WP10. Will now check WP3 from engelsman and integrates it.

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

15 files changed, 288 insertions, 31 deletions

diff --git a/FL/Fl_Box.H b/FL/Fl_Box.H
index 3f6df7113..b6a1475fd 100644
--- a/FL/Fl_Box.H
+++ b/FL/Fl_Box.H
@@ -32,13 +32,27 @@
 #include "Fl_Widget.H"
 #endif
 
+/**
+  This widget simply draws its box, and possibly it's label.  Putting it
+  before some other widgets and making it big enough to surround them
+  will let you draw a frame around them.
+*/
 class FL_EXPORT Fl_Box : public Fl_Widget {
 protected:
   void draw();
 public:
-  Fl_Box(int X, int Y, int W, int H, const char *l=0)
+  /**
+    The first constructor sets box() to FL_NO_BOX, which
+    means it is invisible. However such widgets are useful as placeholders
+    or Fl_Group::resizable()
+    values.  To change the box to something visible, use box(n).
+    <P>The second form of the constructor sets the box to the specified box
+    type.
+  */
+    Fl_Box(int X, int Y, int W, int H, const char *l=0)
 	: Fl_Widget(X,Y,W,H,l) {}
-  Fl_Box(Fl_Boxtype b, int X, int Y, int W, int H, const char *l)
+  /**    See Fl_Box::Fl_Box(int x, int y, int w, int h, const char * = 0)   */
+    Fl_Box(Fl_Boxtype b, int X, int Y, int W, int H, const char *l)
 	: Fl_Widget(X,Y,W,H,l) {box(b);}
 
   virtual int handle(int);
diff --git a/FL/Fl_Repeat_Button.H b/FL/Fl_Repeat_Button.H
index 56e0a3bd7..0087198d1 100644
--- a/FL/Fl_Repeat_Button.H
+++ b/FL/Fl_Repeat_Button.H
@@ -30,10 +30,21 @@
 #include "Fl.H"
 #include "Fl_Button.H"
 
+/**
+  The Fl_Repeat_Button is a subclass of Fl_Button that
+  generates a callback when it is pressed and then repeatedly generates
+  callbacks as long as it is held down.  The speed of the repeat is fixed
+  and depends on the implementation.
+*/
 class FL_EXPORT Fl_Repeat_Button : public Fl_Button {
   static void repeat_callback(void *);
 public:
   int handle(int);
+  /**
+    Creates a new Fl_Repeat_Button widget using the given
+    position, size, and label string. The default boxtype is FL_UP_BOX
+    .
+  */
   Fl_Repeat_Button(int X,int Y,int W,int H,const char *l=0)
     : Fl_Button(X,Y,W,H,l) {}
   void deactivate() {
diff --git a/FL/Fl_Return_Button.H b/FL/Fl_Return_Button.H
index bdc02f617..ea39a7262 100644
--- a/FL/Fl_Return_Button.H
+++ b/FL/Fl_Return_Button.H
@@ -29,11 +29,22 @@
 #define Fl_Return_Button_H
 #include "Fl_Button.H"
 
+/**
+  The Fl_Return_Button is a subclass of Fl_Button that
+  generates a callback when it is pressed or when the user presses the
+  Enter key.  A carriage-return symbol is drawn next to the button label.
+  <P ALIGN=CENTER>\image html Fl_Return_Button.gif
+*/
 class FL_EXPORT Fl_Return_Button : public Fl_Button {
 protected:
   void draw();
 public:
   int handle(int);
+  /**
+    Creates a new Fl_Return_Button widget using the given
+    position, size, and label string. The default boxtype is FL_UP_BOX
+    .
+  */
   Fl_Return_Button(int X, int Y, int W, int H,const char *l=0)
     : Fl_Button(X,Y,W,H,l) {}
 };
diff --git a/FL/Fl_Round_Button.H b/FL/Fl_Round_Button.H
index f1bf6ed0b..c0365add1 100644
--- a/FL/Fl_Round_Button.H
+++ b/FL/Fl_Round_Button.H
@@ -30,6 +30,17 @@
 
 #include "Fl_Light_Button.H"
 
+/**
+  Buttons generate callbacks when they are clicked by the user.  You
+  control exactly when and how by changing the values for type()
+  and when().
+  <P ALIGN=CENTER>\image html Fl_Round_Button.gif</P>
+  <P>The Fl_Round_Button subclass display the &quot;on&quot; state by
+  turning on a light, rather than drawing pushed in.  The shape of the
+  &quot;light&quot; is initially set to FL_ROUND_DOWN_BOX.  The color of the light
+  when on is controlled with selection_color(), which defaults to
+  FL_RED.
+*/
 class FL_EXPORT Fl_Round_Button : public Fl_Light_Button {
 public:
   Fl_Round_Button(int x,int y,int w,int h,const char *l = 0);
diff --git a/FL/Fl_Scroll.H b/FL/Fl_Scroll.H
index 0838c54f0..49390e123 100644
--- a/FL/Fl_Scroll.H
+++ b/FL/Fl_Scroll.H
@@ -31,6 +31,63 @@
 #include "Fl_Group.H"
 #include "Fl_Scrollbar.H"
 
+/**
+  This container widget lets you maneuver around a set of widgets much
+  larger than your window.  If the child widgets are larger than the size
+  of this object then scrollbars will appear so that you can scroll over
+  to them:
+  <P ALIGN=CENTER>\image html Fl_Scroll.gif </P>
+  <P>If all of the child widgets are packed together into a solid
+  rectangle then you want to set box() to FL_NO_BOX or
+  one of the _FRAME types. This will result in the best output.
+  However, if the child widgets are a sparse arrangment you must set 
+  box() to a real _BOX type.  This can result in some
+  blinking during redrawing, but that can be solved by using a 
+  Fl_Double_Window. </P>
+
+  By default you can scroll in both directions, and the scrollbars
+  disappear if the data will fit in the area of the scroll. 
+  <P>Use Fl_Scroll::type() to change this as follows :
+  <UL>
+  <LI>0                            - No scrollbars </LI>
+  <LI>Fl_Scroll::HORIZONTAL        - Only a horizontal scrollbar. </LI>
+  <LI>Fl_Scroll::VERTICAL          - Only a vertical scrollbar. </LI>
+  <LI>Fl_Scroll::BOTH              - The default is both scrollbars. </LI>
+  <LI>Fl_Scroll::HORIZONTAL_ALWAYS - Horizontal scrollbar always on, vertical always off. </LI>
+  <LI>Fl_Scroll::VERTICAL_ALWAYS   - Vertical scrollbar always on, horizontal always off. </LI>
+  <LI>Fl_Scroll::BOTH_ALWAYS       - Both always on. </LI>
+  </UL>
+
+  <P> Use <B> scrollbar.align(int) ( see void Fl_Widget::align(Fl_Align) ) :</B>
+  to change what side the scrollbars are drawn on.<BR>If the 
+  FL_ALIGN_LEFT bit is on, the vertical scrollbar is on the left.
+  If the FL_ALIGN_TOP bit is on, the horizontal scrollbar is on
+  the top. Note that only the alignment flags in scrollbar are 
+  considered. The flags in hscrollbar however are ignored.
+
+  <P>This widget can also be used to pan around a single child widget
+  &quot;canvas&quot;.  This child widget should be of your own class, with a 
+  draw() method that draws the contents.  The scrolling is done by
+  changing the x() and y() of the widget, so this child
+  must use the x() and y() to position it's drawing.
+  To speed up drawing it should test fl_push_clip().
+
+  <P>Another very useful child is a single 
+  Fl_Pack, which is itself a group that packs it's children
+  together and changes size to surround them.  Filling the Fl_Pack
+  with Fl_Tabs groups (and then putting
+  normal widgets inside those) gives you a very powerful scrolling list
+  of individually-openable panels. </P>
+
+  <P>Fluid lets you create these, but you can only lay out objects that
+  fit inside the Fl_Scroll without scrolling.  Be sure to leave
+  space for the scrollbars, as Fluid won't show these either. </P>
+  <P><I>You cannot use Fl_Window as a child of this since the
+  clipping is not conveyed to it when drawn, and it will draw over the
+  scrollbars and neighboring objects.</I>
+*/
+
+*/
 class FL_EXPORT Fl_Scroll : public Fl_Group {
 
   int xposition_, yposition_;
@@ -66,7 +123,9 @@ public:
     BOTH_ALWAYS = 7
   };
 
+  /**    Gets the current horizontal scrolling position.  */
   int xposition() const {return xposition_;}
+  /**    Gets the current vertical scrolling position.  */
   int yposition() const {return yposition_;}
   void scroll_to(int, int);
   void clear();
diff --git a/FL/Fl_Scrollbar.H b/FL/Fl_Scrollbar.H
index 0d474ea0b..43fd7a752 100644
--- a/FL/Fl_Scrollbar.H
+++ b/FL/Fl_Scrollbar.H
@@ -30,6 +30,19 @@
 
 #include "Fl_Slider.H"
 
+/**
+  The Fl_Scrollbar widget displays a slider with arrow buttons
+  at the ends of the scrollbar. Clicking on the arrows move up/left and
+  down/right by linesize().  Scrollbars also accept 
+  FL_SHORTCUT events: the arrows move by linesize(), and
+  vertical scrollbars take Page Up/Down (they move by the page size minus 
+  linesize()) and Home/End (they jump to the top or bottom).
+  <P>Scrollbars have step(1) preset (they always return
+  integers). If desired you can set the step() to non-integer
+  values.  You will then have to use casts to get at the floating-point
+  versions of value() from Fl_Slider. </P>
+  <P ALIGN=CENTER>\image html scrollbar.gif
+*/
 class FL_EXPORT Fl_Scrollbar : public Fl_Slider {
 
   int linesize_;
@@ -45,11 +58,31 @@ public:
   ~Fl_Scrollbar();
   int handle(int);
 
+  /**
+    The first form returns the integer value of the scrollbar. You can get
+    the floating point value with Fl_Slider::value().  The second
+    form sets value(), range(), and slider_size()
+    to make a variable-sized scrollbar. You should call this every time
+    your window changes size, your data changes size, or your scroll
+    position changes (even if in response to a callback from this
+    scrollbar).  All necessary calls to redraw() are done.
+  */
   int value() {return int(Fl_Slider::value());}
+  /**    See int Fl_Scrollbar::value()   */
   int value(int p, int s, int top, int total) {
     return scrollvalue(p, s, top, total);
   }
+  /**
+    This number controls how big the steps are that the arrow keys do.  In
+    addition page up/down move by the size last sent to value()
+    minus one linesize().  The default is 16.
+  */
   int linesize() const {return linesize_;}
+  /**
+    This number controls how big the steps are that the arrow keys do.  In
+    addition page up/down move by the size last sent to value()
+    minus one linesize().  The default is 16.
+  */
   void linesize(int i) {linesize_ = i;}
 
 };
diff --git a/FL/Fl_Valuator.H b/FL/Fl_Valuator.H
index 0959c2dba..7b0446c95 100644
--- a/FL/Fl_Valuator.H
+++ b/FL/Fl_Valuator.H
@@ -36,6 +36,19 @@
 #define FL_VERTICAL		0
 #define FL_HORIZONTAL		1
 
+/**
+  The Fl_Valuator class controls a single floating-point value
+  and provides a consistent interface to set the value, range, and step,
+  and insures that callbacks are done the same for every object.
+  <P>There are probably more of these classes in FLTK than any others: </P>
+  <P ALIGN=CENTER>\image html  src=</P>
+  <P>In the above diagram each box surrounds an actual subclass.  These
+  are further differentiated by setting the 
+  type() of the widget to the symbolic value labeling the
+  widget.  The ones labelled &quot;0&quot; are the default versions with a 
+  type(0).  For consistency the symbol FL_VERTICAL is
+  defined as zero.
+*/
 class FL_EXPORT Fl_Valuator : public Fl_Widget {
 
   double value_;
@@ -58,18 +71,66 @@ protected:
 
 public:
 
-  void bounds(double a, double b) {min=a; max=b;}
-  double minimum() const {return min;}
-  void minimum(double a) {min = a;}
+  /**
+    Sets the minimum (a) and maximum (b) values for
+    the valuator widget.
+  */
+    void bounds(double a, double b) {min=a; max=b;}
+  /**    Gets or sets the minimum value for the valuator.  */
+    double minimum() const {return min;}
+  /**    Gets or sets the minimum value for the valuator.  */
+    void minimum(double a) {min = a;}
+  /**    Gets or sets the maximum value for the valuator.  */
   double maximum() const {return max;}
+  /**    Gets or sets the maximum value for the valuator.  */
   void maximum(double a) {max = a;}
+  /**
+    Sets the minimum and maximum values for the valuator. When
+    the user manipulates the widget, the value is limited to this
+    range. This clamping is done <I>after</I> rounding to the step
+    value (this makes a difference if the range is not a multiple of
+    the step).
+    
+    <P>The minimum may be greater than the maximum. This has the
+    effect of &quot;reversing&quot; the object so the larger values
+    are in the opposite direction. This also switches which end of
+    the filled sliders is filled.</P>
+    
+    <P>Some widgets consider this a &quot;soft&quot; range.  This
+    means they will stop at the range, but if the user releases and
+    grabs the control again and tries to move it further, it is
+    allowed.</P>
+    
+    <P>The range may affect the display. You must redraw()
+    the widget after changing the range.
+  */
   void range(double a, double b) {min = a; max = b;}
+  /**    See double Fl_Valuator::step() const   */
   void step(int a) {A = a; B = 1;}
+  /**    See double Fl_Valuator::step() const   */
   void step(double a, int b) {A = a; B = b;}
   void step(double s);
+  /**
+    Gets or sets the step value. As the user moves the mouse the
+    value is rounded to the nearest multiple of the step value. This
+    is done <I>before</I> clamping it to the range. For most widgets
+    the default step is zero.
+    
+    <P>For precision the step is stored as the ratio of two
+    integers, A/B. You can set these integers directly. Currently
+    setting a floating point value sets the nearest A/1 or 1/B value
+    possible.
+  */
   double step() const {return A/B;}
   void precision(int);
 
+  /**
+    Gets or sets the current value. The new value is <I>not</I>
+    clamped or otherwise changed before storing it. Use
+    clamp() or round() to modify the value before
+    calling value(). The widget is redrawn if the new value
+    is different than the current one. The initial value is zero.
+  */
   double value() const {return value_;}
   int value(double);
 
diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt
index 74c65362c..e89c0276a 100644
--- a/documentation/todo_filelist_doc.txt
+++ b/documentation/todo_filelist_doc.txt
@@ -16,9 +16,9 @@ In Progress Work List (add your WP and name here):
   - WP5  (Fabien) DONE
   - WP6  (Fabien) DONE
   - WP7  (Fabien) DONE
-  - WP8  (Fabien)
-  - WP9
-  - WP10
+  - WP8  (Fabien) DONE
+  - WP9  (Fabien)
+  - WP10 (Fabien)
   - WP11
   - WP12 (Albrecht) work in progress
   - WP13 (Albrecht) work in progress
@@ -156,8 +156,6 @@ widgets.html
 Enumerations.H		(Albrecht) work in progress !
 Fl_Adjuster.H
 Fl_Adjuster.cxx
-Fl_Box.H
-Fl_Box.cxx
 Fl_Button.H
 Fl_Button.cxx
 Fl_Chart.H
@@ -205,19 +203,9 @@ Fl_Output.H
 Fl_Radio_Button.H
 Fl_Radio_Light_Button.H
 Fl_Radio_Round_Button.H
-Fl_Repeat_Button.H
-Fl_Repeat_Button.cxx
-Fl_Return_Button.H
-Fl_Return_Button.cxx
 Fl_Roller.H
 Fl_Roller.cxx
-Fl_Round_Button.H
-Fl_Round_Button.cxx
 Fl_Round_Clock.H
-Fl_Scroll.H
-Fl_Scroll.cxx
-Fl_Scrollbar.H
-Fl_Scrollbar.cxx
 Fl_Secret_Input.H
 Fl_Select_Browser.H
 Fl_Simple_Counter.H
@@ -241,8 +229,6 @@ Fl_Toggle_Light_Button.H
 Fl_Toggle_Round_Button.H
 Fl_Tooltip.H
 Fl_Tooltip.cxx
-Fl_Valuator.H
-Fl_Valuator.cxx
 Fl_Value_Input.H
 Fl_Value_Input.cxx
 Fl_Value_Output.H
diff --git a/src/Fl_Box.cxx b/src/Fl_Box.cxx
index b8107e9f8..c56ae1bbd 100644
--- a/src/Fl_Box.cxx
+++ b/src/Fl_Box.cxx
@@ -25,6 +25,9 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn Fl_Box::~Fl_Box(void)
+  The destructor removes the box.*/
+
 #include <FL/Fl_Widget.H>
 #include <FL/Fl_Box.H>
 
diff --git a/src/Fl_Repeat_Button.cxx b/src/Fl_Repeat_Button.cxx
index 2252a3a24..41d0ec779 100644
--- a/src/Fl_Repeat_Button.cxx
+++ b/src/Fl_Repeat_Button.cxx
@@ -25,6 +25,9 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn virtual Fl_Repeat_Button::~Fl_Repeat_Button()
+  Deletes the button.*/
+
 #include <FL/Fl.H>
 #include <FL/Fl_Repeat_Button.H>
 
diff --git a/src/Fl_Return_Button.cxx b/src/Fl_Return_Button.cxx
index d09f62265..09a22cac5 100644
--- a/src/Fl_Return_Button.cxx
+++ b/src/Fl_Return_Button.cxx
@@ -25,6 +25,9 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn virtual Fl_Return_Button::~Fl_Return_Button()
+  Deletes the button.*/
+
 #include <FL/Fl.H>
 #include <FL/Fl_Return_Button.H>
 #include <FL/fl_draw.H>
diff --git a/src/Fl_Round_Button.cxx b/src/Fl_Round_Button.cxx
index 7ea65bfd0..d86611e0c 100644
--- a/src/Fl_Round_Button.cxx
+++ b/src/Fl_Round_Button.cxx
@@ -32,6 +32,10 @@
 #include <FL/Fl.H>
 #include <FL/Fl_Round_Button.H>
 
+/**
+  Creates a new Fl_Round_Button widget using the given
+  position, size, and label string.
+*/
 Fl_Round_Button::Fl_Round_Button(int X,int Y,int W,int H, const char *l)
 : Fl_Light_Button(X,Y,W,H,l) {
   box(FL_NO_BOX);
diff --git a/src/Fl_Scroll.cxx b/src/Fl_Scroll.cxx
index 701aa2dd3..ae575024f 100644
--- a/src/Fl_Scroll.cxx
+++ b/src/Fl_Scroll.cxx
@@ -30,7 +30,7 @@
 #include <FL/Fl_Scroll.H>
 #include <FL/fl_draw.H>
 
-// Clear all but the scrollbars...
+/** Clear all but the scrollbars... */
 void Fl_Scroll::clear() {
   for (int i=children() - 1; i >= 0; i --) {
     Fl_Widget* o = child(i);
@@ -41,7 +41,7 @@ void Fl_Scroll::clear() {
   }
 }
 
-// Insure the scrollbars are the last children:
+/** Insure the scrollbars are the last children */
 void Fl_Scroll::fix_scrollbar_order() {
   Fl_Widget** a = (Fl_Widget**)array();
   if (a[children()-1] != &scrollbar) {
@@ -259,6 +259,7 @@ void Fl_Scroll::resize(int X, int Y, int W, int H) {
   }
 }
 
+/**  Moves the contents of the scroll group to a new position.*/
 void Fl_Scroll::scroll_to(int X, int Y) {
   int dx = xposition_-X;
   int dy = yposition_-Y;
@@ -284,7 +285,16 @@ void Fl_Scroll::scrollbar_cb(Fl_Widget* o, void*) {
   Fl_Scroll* s = (Fl_Scroll*)(o->parent());
   s->scroll_to(s->xposition(), int(((Fl_Scrollbar*)o)->value()));
 }
-
+/**
+  Creates a new Fl_Scroll widget using the given position,
+  size, and label string. The default boxtype is FL_NO_BOX.
+  <B>The destructor <I>also deletes all the children</I>. This allows a
+  whole tree to be deleted at once, without having to keep a pointer to
+  all the children in the user code. A kludge has been done so the 
+  Fl_Scroll and all of it's children can be automatic (local)
+  variables, but you must declare the Fl_Scroll<I>first</I>, so
+  that it is destroyed last.
+*/
 Fl_Scroll::Fl_Scroll(int X,int Y,int W,int H,const char* L)
   : Fl_Group(X,Y,W,H,L), 
     scrollbar(X+W-Fl::scrollbar_size(),Y,
diff --git a/src/Fl_Scrollbar.cxx b/src/Fl_Scrollbar.cxx
index b2c50905f..765adde00 100644
--- a/src/Fl_Scrollbar.cxx
+++ b/src/Fl_Scrollbar.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 
+
 #include <FL/Fl.H>
 #include <FL/Fl_Scrollbar.H>
 #include <FL/fl_draw.H>
@@ -254,9 +255,13 @@ void Fl_Scrollbar::draw() {
   }
 }
 
+/**
+  Creates a new Fl_Scrollbar widget using the given position,
+  size, and label string.  You need to do type(FL_HORIZONTAL) if
+  you want a horizontal scrollbar.
+*/
 Fl_Scrollbar::Fl_Scrollbar(int X, int Y, int W, int H, const char* L)
-  : Fl_Slider(X, Y, W, H, L)
-{
+  : Fl_Slider(X, Y, W, H, L) {
   box(FL_FLAT_BOX);
   color(FL_DARK2);
   slider(FL_UP_BOX);
@@ -265,8 +270,8 @@ Fl_Scrollbar::Fl_Scrollbar(int X, int Y, int W, int H, const char* L)
   step(1);
 }
 
-Fl_Scrollbar::~Fl_Scrollbar()
-{
+/**  Destroys the Scrollbar. */
+Fl_Scrollbar::~Fl_Scrollbar() {
   if (pushed_)
     Fl::remove_timeout(timeout_cb, this);
 }
diff --git a/src/Fl_Valuator.cxx b/src/Fl_Valuator.cxx
index 296951022..faeb4f2b5 100644
--- a/src/Fl_Valuator.cxx
+++ b/src/Fl_Valuator.cxx
@@ -25,6 +25,12 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn int Fl_Valuator::changed() const
+  This value is true if the user has moved the slider. It is
+  turned off by value(x) and just before doing a callback
+  (the callback can turn it back on if desired).
+*/
+
 // Base class for sliders and all other one-value "knobs"
 
 #include <FL/Fl.H>
@@ -34,7 +40,11 @@
 #include "flstring.h"
 
 Fl_Valuator::Fl_Valuator(int X, int Y, int W, int H, const char* L)
-  : Fl_Widget(X,Y,W,H,L) {
+/**
+  Creates a new Fl_Valuator widget using the given position,
+  size, and label string. The default boxtype is FL_NO_BOX.
+*/
+: Fl_Widget(X,Y,W,H,L) {
   align(FL_ALIGN_BOTTOM);
   when(FL_WHEN_CHANGED);
   value_ = 0;
@@ -47,6 +57,7 @@ Fl_Valuator::Fl_Valuator(int X, int Y, int W, int H, const char* L)
 
 const double epsilon = 4.66e-10;
 
+/**  See double Fl_Valuator::step() const */
 void Fl_Valuator::step(double s) {
   if (s < 0) s = -s;
   A = rint(s);
@@ -54,13 +65,15 @@ void Fl_Valuator::step(double s) {
   while (fabs(s-A/B) > epsilon && B<=(0x7fffffff/10)) {B *= 10; A = rint(s*B);}
 }
 
+/**  Sets the step value to 1/10<SUP>digits.*/
 void Fl_Valuator::precision(int p) {
   A = 1.0;
   for (B = 1; p--;) B *= 10;
 }
-
+/** Asks for partial redraw */
 void Fl_Valuator::value_damage() {damage(FL_DAMAGE_EXPOSE);} // by default do partial-redraw
 
+/**  See double Fl_Valuator::value() const */
 int Fl_Valuator::value(double v) {
   clear_changed();
   if (v == value_) return 0;
@@ -101,23 +114,53 @@ void Fl_Valuator::handle_release() {
   }
 }
 
+/**
+  Round the passed value to the nearest step increment.  Does
+  nothing if step is zero.
+*/
 double Fl_Valuator::round(double v) {
   if (A) return rint(v*B/A)*A/B;
   else return v;
 }
 
+/**  Clamps the passed value to the valuator range.*/
 double Fl_Valuator::clamp(double v) {
   if ((v<min)==(min<=max)) return min;
   else if ((v>max)==(min<=max)) return max;
   else return v;
 }
 
+/**
+  Adds n times the step value to the passed value. If
+  step was set to zero it uses fabs(maximum() - minimum()) /
+  100.
+*/
 double Fl_Valuator::increment(double v, int n) {
   if (!A) return v+n*(max-min)/100;
   if (min > max) n = -n;
   return (rint(v*B/A)+n)*A/B;
 }
 
+/**
+  Uses internal rules to format the fields numerical value into
+  the character array pointed to by the passed parameter.</P>
+  
+  <P>The actual format used depends on the current step value. If
+  the step value has been set to zero then a %g format is used.
+  If the step value is non-zero, then a %.*f format is used,
+  where the precision is calculated to show sufficient digits
+  for the current step value. An integer step value, such as 1
+  or 1.0, gives a precision of 0, so the formatted value will
+  appear as an integer.</P>
+  
+  <P>This method is used by the Fl_Value_... group of widgets to 
+  format the current value into a text string. 
+  The return value is the length of the formatted text.
+  The formatted value is written into in <i>buffer</i>. 
+  <i>buffer</i> should have space for at least 128 bytes.</P>
+  
+  <P>You may override this function to create your own text formatting.
+*/
 int Fl_Valuator::format(char* buffer) {
   double v = value();
   // MRS: THIS IS A HACK - RECOMMEND ADDING BUFFER SIZE ARGUMENT