Improve documentation of Fl_Valuator class.

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

2 files changed, 42 insertions, 37 deletions

diff --git a/FL/Fl_Valuator.H b/FL/Fl_Valuator.H
index 6ec496aab..9fc36f7bf 100644
--- a/FL/Fl_Valuator.H
+++ b/FL/Fl_Valuator.H
@@ -3,7 +3,7 @@
 //
 // Valuator header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -34,13 +34,16 @@
   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 ALIGN=CENTER>\image html  valuators.png</P> 
-  \image latex   valuators.png "Valuators derived from Fl_Valuators" width=10cm
-  <P>In the above diagram each box surrounds an actual subclass.  These
-  are further differentiated by setting the type() of the widget t
-  o the symbolic value labeling the widget.  
-  The ones labelled "0" are the default versions with a type(0).  
+
+  There are probably more of these classes in FLTK than any others:
+
+  <P ALIGN=CENTER>\image html valuators.png</P>
+  \image latex valuators.png "Valuators derived from Fl_Valuators" width=10cm
+
+  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 "0" 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 {
@@ -84,18 +87,18 @@ public:
     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
+
+    The minimum may be greater than the maximum. This has the
     effect of "reversing" 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 "soft" range.  This
+    the filled sliders is filled.
+
+    Some widgets consider this a "soft" 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()
+    allowed.
+
+    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;}
@@ -107,16 +110,16 @@ public:
   /**
     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
+    is done \e before 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
+
+    For precision the step is stored as the ratio of a double \p A and
+    an integer \p B = A/B. You can set these values 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);
+  void precision(int digits);
 
   /** Gets the floating point(double) value. See int value(double) */
   double value() const {return value_;}
diff --git a/src/Fl_Valuator.cxx b/src/Fl_Valuator.cxx
index dcc3bf1b6..3be6a29ed 100644
--- a/src/Fl_Valuator.cxx
+++ b/src/Fl_Valuator.cxx
@@ -3,7 +3,7 @@
 //
 // Valuator widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -65,16 +65,18 @@ void Fl_Valuator::precision(int digits) {
   A = 1.0;
   for (B = 1; digits--;) B *= 10;
 }
-/** Asks for partial redraw */
+
+/**  Asks for partial redraw */
 void Fl_Valuator::value_damage() {damage(FL_DAMAGE_EXPOSE);} // by default do partial-redraw
 
 /**
-    Sets the current value. The new value is <I>not</I>
+    Sets the current value. The new value is \e not
     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.
-    <P>changed() will return true if the user has moved the slider,
+
+    changed() will return true if the user has moved the slider,
     but it will be turned off by value(x) and just before doing a callback
     (the callback can turn it back on if desired).
 */
@@ -147,23 +149,23 @@ double Fl_Valuator::increment(double v, int n) {
 
 /**
   Uses internal rules to format the fields numerical value into
-  the character array pointed to by the passed parameter.</P>
+  the character array pointed to by the passed parameter.
   
-  <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,
+  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. 
+  appear as an integer.
+
+  This method is used by the Fl_Valuator_... 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.
+  The formatted value is written into \p buffer.
+  \p buffer should have space for at least 128 bytes.
+
+  You may override this function to create your own text formatting.
 */
 int Fl_Valuator::format(char* buffer) {
   double v = value();