From 2be88792b3746c72d82448f8373bc7d6b322d38a Mon Sep 17 00:00:00 2001
From: Fabien Costantini <fabien@onepost.net>
Date: Wed, 17 Sep 2008 22:25:45 +0000
Subject: [PATCH] Doxygen documentation: fixed all ambiguous methods
 signatures, fixed erroneous path test into ../test since the doxyfile move,
 fixed all intro dl,dt,dd related tags warnings in intro.dox .

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6289 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 FL/Fl_Browser.H            |  4 ++--
 FL/Fl_Output.H             |  2 +-
 FL/Fl_Preferences.H        | 12 ++++++------
 FL/Fl_Return_Button.H      |  4 ++--
 FL/Fl_Spinner.H            | 28 ++++++++++++++--------------
 FL/Fl_Valuator.H           | 19 ++++++-------------
 FL/Fl_Widget.H             |  4 ++--
 documentation/Doxyfile     |  2 +-
 documentation/intro.dox    | 33 ++++++++++++++++++---------------
 src/Fl_BMP_Image.cxx       |  6 ++----
 src/Fl_File_Chooser2.cxx   |  3 +--
 src/Fl_Gl_Window.cxx       |  1 -
 src/Fl_Help_Dialog_Dox.cxx |  2 +-
 src/Fl_Preferences.cxx     |  4 ++--
 src/Fl_Return_Button.cxx   |  3 ---
 src/Fl_Scroll.cxx          |  2 +-
 src/Fl_Valuator.cxx        | 18 +++++++++++-------
 src/Fl_Value_Slider.cxx    |  3 +--
 18 files changed, 71 insertions(+), 79 deletions(-)

diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H
index a31149c03..0955d87bf 100644
--- a/FL/Fl_Browser.H
+++ b/FL/Fl_Browser.H
@@ -158,8 +158,8 @@ public:
     <UL>
     <LI><tt>'\@.'</tt> Print rest of line, don't look for more '\@' signs </LI>
     <LI><tt>'\@\@'</tt> Print rest of line starting with '\@' </LI>
-    <LI><tt>'\@l'</tt> Use a <BIG>large</BIG> (24 point) font </LI>
-    <LI><tt>'\@m'</tt> Use a <BIG>medium large</BIG> (18 point) font </LI>
+    <LI><tt>'\@l'</tt> Use a LARGE (24 point) font </LI>
+    <LI><tt>'\@m'</tt> Use a medium large (18 point) font </LI>
     <LI><tt>'\@s'</tt> Use a <SMALL>small</SMALL> (11 point) font </LI>
     <LI><tt>'\@b'</tt> Use a <B>bold</B> font (adds FL_BOLD to font) </LI>
     <LI><tt>'\@i'</tt> Use an <I>italic</I> font (adds FL_ITALIC to font) </LI>
diff --git a/FL/Fl_Output.H b/FL/Fl_Output.H
index b9ea12032..8e8bfeebd 100644
--- a/FL/Fl_Output.H
+++ b/FL/Fl_Output.H
@@ -38,7 +38,7 @@
   which is useful for program-generated values.  The user may select
   portions of the text using the mouse and paste the contents into other
   fields or programs.
-  <CENTER>\image html text.gif</CENTER>
+  <P align=CENTER>\image html text.gif</P>
   <P>There is a single subclass, 
   Fl_Multiline_Output, which allows you to display multiple lines of
   text. </P>
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 6ed132f95..7ff43e9f5 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -151,10 +151,10 @@ public:
      order  of group names. The index must be within the range given
      by groups().
      
-     \param[in] index number indexing the requested group
+     \param[in] num_group number indexing the requested group
      \return cstring pointer to the group name
    */
-  const char *group( int index );
+  const char *group( int num_group );
   
   /**
      Returns non-zero if a group with this name exists.
@@ -162,10 +162,10 @@ public:
      "." describes the current node, "./" describes the topmost node.
      By preceding a groupname with a "./", its path becomes relative to the topmost node.
      
-     \param[in] group name of group that is searched for
+     \param[in] key name of group that is searched for
      \return 0 if group was not found
    */
-  char groupExists( const char *group );
+  char groupExists( const char *key );
 
   /**
      Deletes a group.
@@ -196,10 +196,10 @@ public:
   /**
      Returns non-zero if an entry with this name exists.
      
-     \param[in] entry name of entry that is searched for
+     \param[in] key name of entry that is searched for
      \return 0 if entry was not found
    */
-  char entryExists( const char *entry );
+  char entryExists( const char *key );
   
   /**
      Removes a single entry (name/value pair).
diff --git a/FL/Fl_Return_Button.H b/FL/Fl_Return_Button.H
index 06947ee58..c7e9813d9 100644
--- a/FL/Fl_Return_Button.H
+++ b/FL/Fl_Return_Button.H
@@ -45,8 +45,8 @@ 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
-    .
+    position, size, and label string. The default boxtype is FL_UP_BOX.
+    <P> The inherited destructor deletes the button.
   */
   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_Spinner.H b/FL/Fl_Spinner.H
index 73e549f13..f91eadbf5 100644
--- a/FL/Fl_Spinner.H
+++ b/FL/Fl_Spinner.H
@@ -176,15 +176,15 @@ class Fl_Spinner : public Fl_Group
 
   /** Speling mistakes retained for source compatibility \deprecated */
   double	maxinum() const { return (maximum_); }
-  /** Sets or returns the maximum value of the widget. */
+  /** Gets the maximum value of the widget. */
   double	maximum() const { return (maximum_); }
-  /** Sets or returns the maximum value of the widget. */
+  /** Sets the maximum value of the widget. */
   void		maximum(double m) { maximum_ = m; }
   /** Speling mistakes retained for source compatibility \deprecated */
   double	mininum() const { return (minimum_); }
-  /** Sets or returns the minimum value of the widget. */
+  /** Gets the minimum value of the widget. */
   double	minimum() const { return (minimum_); }
-  /** Sets or returns the minimum value of the widget. */
+  /** Sets the minimum value of the widget. */
   void		minimum(double m) { minimum_ = m; }
   /** Sets the minimum and maximum values for the widget. */
   void		range(double a, double b) { minimum_ = a; maximum_ = b; }
@@ -209,31 +209,31 @@ class Fl_Spinner : public Fl_Group
 		  else input_.type(FL_INT_INPUT);
 		  update();
 		}
-  /** Sets or Gets the color of the text in the input field. */
+  /** Gets the color of the text in the input field. */
   Fl_Color	textcolor() const {
 		  return (input_.textcolor());
 		}
-  /** Sets or Gets the color of the text in the input field. */
+  /** Sets the color of the text in the input field. */
   void		textcolor(Fl_Color c) {
 		  input_.textcolor(c);
 		}
-  /** Sets or Gets the font of the text in the input field. */
+  /** Gets the font of the text in the input field. */
   Fl_Font       textfont() const {
 		  return (input_.textfont());
 		}
-  /** Sets or Gets the font of the text in the input field. */
+  /** Sets the font of the text in the input field. */
   void		textfont(Fl_Font f) {
 		  input_.textfont(f);
 		}
-  /** Sets or Gets the size of the text in the input field. */
+  /** Gets the size of the text in the input field. */
   Fl_Fontsize  textsize() const {
 		  return (input_.textsize());
 		}
-  /** Sets or Gets the size of the text in the input field. */
+  /** Sets the size of the text in the input field. */
   void		textsize(Fl_Fontsize s) {
 		  input_.textsize(s);
 		}
-  /** Sets or returns the numeric representation in the input field.
+  /** Sets or Gets the numeric representation in the input field.
     Valid values are FL_INT_INPUT and FL_FLOAT_INPUT.
     The first form also changes the format() template.
     Setting a new spinner type via a superclass pointer will not work.
@@ -249,13 +249,13 @@ class Fl_Spinner : public Fl_Group
                   }
                   input_.type(v); 
                 }
+  /** Gets the current value of the widget. */
+  double	value() const { return (value_); }
   /**
-    Sets or returns the current value of the widget.
+    Sets the current value of the widget.
     Before setting value to a non-integer value, the spinner 
     type() should be changed to floating point. 
   */
-  double	value() const { return (value_); }
-  /** See double Fl_Spinner::value() const */
   void		value(double v) { value_ = v; update(); }
 };
 
diff --git a/FL/Fl_Valuator.H b/FL/Fl_Valuator.H
index a90e60223..eb2d8a814 100644
--- a/FL/Fl_Valuator.H
+++ b/FL/Fl_Valuator.H
@@ -43,14 +43,13 @@
   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>There are probably more of these classes in FLTK than any others:
   <P ALIGN=CENTER>\image html  valuators.gif</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 "0" are the default versions with a 
-  type(0).  For consistency the symbol FL_VERTICAL is
-  defined as zero.
+  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).  
+  For consistency the symbol FL_VERTICAL is defined as zero.
 */
 class FL_EXPORT Fl_Valuator : public Fl_Widget {
 
@@ -124,13 +123,7 @@ public:
   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.
-  */
+  /** Gets the floating point(double) value. See int value(double) */
   double value() const {return value_;}
   int value(double);
 
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index 67741b228..fbdd61524 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -249,9 +249,9 @@ public:
   int damage_resize(int,int,int,int);
 
   /** Reposition the window or widget.
-   *  position(x,y) is a shortcut for resize(x,y,w(),h()).
+   *  position(X,Y) is a shortcut for resize(X,Y,w(),h()).
    *
-   *  \param[in] x, y new position relative to the parent window 
+   *  \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_);}
diff --git a/documentation/Doxyfile b/documentation/Doxyfile
index 06fa1d9dc..d8ca0507a 100644
--- a/documentation/Doxyfile
+++ b/documentation/Doxyfile
@@ -576,7 +576,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = test
+EXAMPLE_PATH           = ../test
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
diff --git a/documentation/intro.dox b/documentation/intro.dox
index 590e191d2..a2c7d89ca 100644
--- a/documentation/intro.dox
+++ b/documentation/intro.dox
@@ -315,25 +315,28 @@ make
 
 <DL>
 
-	<DT>WWW
-	<DD><A href="http://www.fltk.org/">http://www.fltk.org/</A>
-	<DD><A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A> 
+	<DT>WWW</DT>
+	<DD>
+	<A href="http://www.fltk.org/">http://www.fltk.org/</A>
+	<A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A> 
 	  [for reporting bugs]
-	<DD><A href="http://www.fltk.org/software.php">http://www.fltk.org/software.php</A> 
+	<A href="http://www.fltk.org/software.php">http://www.fltk.org/software.php</A> 
 	  [source code]
-
-	<DT>FTP
-	<DD><A HREF="ftp://ftp.fltk.org/pub/fltk">California, USA (ftp.fltk.org)</A>
-	<DD><A HREF="ftp://ftp2.fltk.org/pub/fltk">Maryland, USA (ftp2.fltk.org)</A>
-	<DD><A HREF="ftp://ftp.funet.fi/pub/mirrors/ftp.fltk.org/pub/fltk">Espoo, Finland (ftp.funet.fi)</A>
-	<DD><A HREF="ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk">Germany (linux.mathematik.tu-darmstadt.de)</A>
-	<DD><A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A>
+	</DD>
+	<DT>FTP</DT>
+    <DD>
+    <A HREF="ftp://ftp.fltk.org/pub/fltk">California, USA (ftp.fltk.org)</A>
+	<A HREF="ftp://ftp2.fltk.org/pub/fltk">Maryland, USA (ftp2.fltk.org)</A>
+	<A HREF="ftp://ftp.funet.fi/pub/mirrors/ftp.fltk.org/pub/fltk">Espoo, Finland (ftp.funet.fi)</A>
+	<A HREF="ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk">Germany (linux.mathematik.tu-darmstadt.de)</A>
+	<A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A>
+	</DD>
 
 	<DT>EMail</DT>
-	<DD><A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see
-	instructions below]
-	<DD><A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for
-	reporting bugs]
+	<DD>
+	<A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see instructions below]
+	<A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for	reporting bugs]
+	</DD>
 
 	<DT>NNTP Newsgroups</DT>
 	<DD>news.easysw.com</DD>
diff --git a/src/Fl_BMP_Image.cxx b/src/Fl_BMP_Image.cxx
index 4c5e31da6..ba2587846 100644
--- a/src/Fl_BMP_Image.cxx
+++ b/src/Fl_BMP_Image.cxx
@@ -59,14 +59,12 @@
 static int		read_long(FILE *fp);
 static unsigned short	read_word(FILE *fp);
 static unsigned int	read_dword(FILE *fp);
-/** \fn Fl_BMP_Image::~Fl_BMP_Image()
-*/
-
-
 /** 
   The constructor loads the named BMP image from the given bmp filename.  
   <P>The inherited destructor free all memory and server resources that are used by
   the image.
+  <P>The destructor free all memory and server resources that are used by
+  the image
 */
 Fl_BMP_Image::Fl_BMP_Image(const char *bmp) // I - File to read
   : Fl_RGB_Image(0,0,0) {
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index 9cf693a1f..0484b5f3d 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -31,7 +31,7 @@
   The Fl_File_Chooser widget displays a standard file selection
   dialog that supports various selection modes.
   
-  <CENTER>\image html Fl_File_Chooser.jpg</CENTER>
+    <P ALIGN=CENTER>\image html Fl_File_Chooser.jpg</P>
   
   <P>The Fl_File_Chooser class also exports several static values
   that may be used to localize or customize the appearance of all file chooser
@@ -100,7 +100,6 @@
   	<TD>fl_numericsort</TD>
   </TR>
   </TABLE></CENTER>
-  
   <P>The sort member specifies the sort function that is
   used when loading the contents of a directory.
 */
diff --git a/src/Fl_Gl_Window.cxx b/src/Fl_Gl_Window.cxx
index 65c4a0e8d..c177819e6 100644
--- a/src/Fl_Gl_Window.cxx
+++ b/src/Fl_Gl_Window.cxx
@@ -25,7 +25,6 @@
 //     http://www.fltk.org/str.php
 //
 
-
 #include "flstring.h"
 #if HAVE_GL
 
diff --git a/src/Fl_Help_Dialog_Dox.cxx b/src/Fl_Help_Dialog_Dox.cxx
index f41f84032..c9febddac 100644
--- a/src/Fl_Help_Dialog_Dox.cxx
+++ b/src/Fl_Help_Dialog_Dox.cxx
@@ -31,7 +31,7 @@
   The Fl_Help_Dialog widget displays a standard help dialog window
   using the Fl_Help_View widget.
   
-  <CENTER>\image html Fl_Help_Dialog.gif</CENTER>
+  <P ALIGN=CENTER> \image html Fl_Help_Dialog.gif </P>
 */
 
 /** \fn Fl_Help_Dialog::Fl_Help_Dialog()
diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index 28b6950a4..a44509a0b 100644
--- a/src/Fl_Preferences.cxx
+++ b/src/Fl_Preferences.cxx
@@ -142,9 +142,9 @@ int Fl_Preferences::groups()
  * - the index must be within the range given by groups()
  * example: printf( "Group(%d)='%s'\n", ix, base.group(ix) );
  */
-const char *Fl_Preferences::group( int ix )
+const char *Fl_Preferences::group( int num_group )
 {
-  return node->child( ix );
+  return node->child( num_group );
 }
 
 
diff --git a/src/Fl_Return_Button.cxx b/src/Fl_Return_Button.cxx
index 7f0a42b13..7a520c948 100644
--- a/src/Fl_Return_Button.cxx
+++ b/src/Fl_Return_Button.cxx
@@ -25,9 +25,6 @@
 //     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_Scroll.cxx b/src/Fl_Scroll.cxx
index 2014d7bd7..29c4c3d33 100644
--- a/src/Fl_Scroll.cxx
+++ b/src/Fl_Scroll.cxx
@@ -288,7 +288,7 @@ void Fl_Scroll::scrollbar_cb(Fl_Widget* o, void*) {
 /**
   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
+  <P>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)
diff --git a/src/Fl_Valuator.cxx b/src/Fl_Valuator.cxx
index 8e552ba78..7a76220df 100644
--- a/src/Fl_Valuator.cxx
+++ b/src/Fl_Valuator.cxx
@@ -25,11 +25,6 @@
 //     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"
 
@@ -65,7 +60,7 @@ 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.*/
+/**  Sets the step value to 1/10<SUP>digits</SUP>.*/
 void Fl_Valuator::precision(int p) {
   A = 1.0;
   for (B = 1; p--;) B *= 10;
@@ -73,7 +68,16 @@ void Fl_Valuator::precision(int p) {
 /** Asks for partial redraw */
 void Fl_Valuator::value_damage() {damage(FL_DAMAGE_EXPOSE);} // by default do partial-redraw
 
-/**  See double Fl_Valuator::value() const */
+/**
+    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.
+    <P>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).
+*/
 int Fl_Valuator::value(double v) {
   clear_changed();
   if (v == value_) return 0;
diff --git a/src/Fl_Value_Slider.cxx b/src/Fl_Value_Slider.cxx
index 6b666645f..9c3a71fe1 100644
--- a/src/Fl_Value_Slider.cxx
+++ b/src/Fl_Value_Slider.cxx
@@ -32,8 +32,7 @@
 
 /**
   Creates a new Fl_Value_Slider widget using the given
-  position, size, and label string. The default boxtype is FL_DOWN_BOX
-  .
+  position, size, and label string. The default boxtype is FL_DOWN_BOX.
 */
 Fl_Value_Slider::Fl_Value_Slider(int X, int Y, int W, int H, const char*l)
 : Fl_Slider(X,Y,W,H,l) {