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

7 files changed, 80 insertions, 9 deletions

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