Doxygen Documentation WP6 Done, Also completed the documentation of Help_View, Help_Dialog and cleaned up Preferences from ugly stars in comments and also removed redundant get/set text from methods doc. In this increment, we don't bother with the old dox format (comments in header). We have better things to do with our time (like about 40 mores files to doxyfy :-).

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

4 files changed, 151 insertions, 52 deletions

diff --git a/src/Fl_Help_Dialog_Dox.cxx b/src/Fl_Help_Dialog_Dox.cxx
new file mode 100644
index 000000000..e7f753434
--- /dev/null
+++ b/src/Fl_Help_Dialog_Dox.cxx
@@ -0,0 +1,119 @@
+//
+// "$Id"
+//
+// Fl_Help_Dialog dialog for the Fast Light Tool Kit (FLTK).
+//
+// Copyright 1998-2005 by Bill Spitzak and others.
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Library General Public License for more details.
+//
+// You should have received a copy of the GNU Library General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+// USA.
+//
+// Please report all bugs and problems on the following page:
+//
+//     http://www.fltk.org/str.php
+//
+
+// Fl_Help_Dialog (autogenerated class) doxygen documentation placeholder
+
+/** \class Fl_Help_Dialog
+  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>
+*/
+
+/** \fn Fl_Help_Dialog::Fl_Help_Dialog()
+  The constructor creates the dialog pictured above.*/
+
+/** \fn Fl_Help_Dialog::~Fl_Help_Dialog()
+  The destructor destroys the widget and frees all memory that has been
+  allocated for the current file.
+*/
+
+/** \fn void Fl_Help_Dialog::hide()
+  Hides the Fl_Help_Dialog window.*/
+
+/** \fn void Fl_Help_Dialog::load(const char *f)
+  Loads the specified HTML file into the Fl_Help_View widget.
+  The filename can also contain a target name ("filename.html#target").
+*/
+
+/** \fn void Fl_Help_Dialog::position(int x, int y)
+  Set the screen position of the dialog.*/
+
+/** \fn void Fl_Help_Dialog::resize(int xx, int yy, int ww, int hh)
+  Change the position and size of the dialog.*/
+
+/** \fn void Fl_Help_Dialog::show()
+  Shows the Fl_Help_Dialog window.*/
+
+/** \fn void Fl_Help_Dialog::textsize(uchar s)
+  Sets or gets the default text size for the help view.*/
+
+/** \fn uchar Fl_Help_Dialog::textsize()
+  Sets or gets the default text size for the help view.*/
+
+/** \fn void Fl_Help_Dialog::topline(const char *n)
+  Sets the top line in the Fl_Help_View widget to the named or
+  numbered line.
+*/
+
+/** \fn void Fl_Help_Dialog::topline(int n)
+  Sets the top line in the Fl_Help_View widget to the named or
+  numbered line.
+*/
+
+/** \fn void Fl_Help_Dialog::value(const char *v)
+  The first form sets the current buffer to the string provided and
+  reformats the text. It also clears the history of the "back" and
+  "forward" buttons. The second form returns the current buffer contents.
+*/
+
+/** \fn const char *Fl_Help_Dialog::value() const
+  The first form sets the current buffer to the string provided and
+  reformats the text. It also clears the history of the "back" and
+  "forward" buttons. The second form returns the current buffer contents.
+*/
+
+/** \fn int Fl_Help_Dialog::visible()
+  Returns 1 if the Fl_Help_Dialog window is visible.*/
+
+/** \fn int Fl_Help_Dialog::x()
+  Returns the position and size of the help dialog.*/
+
+/** \fn int Fl_Help_Dialog::y()
+  Returns the position and size of the help dialog.*/
+
+/** \fn int Fl_Help_Dialog::w()
+  Returns the position and size of the help dialog.*/
+
+/** \fn int Fl_Help_Dialog::h()
+  Returns the position and size of the help dialog.*/
+
+/** \fn void Fl_Help_Dialog::show()
+  Shows the main Help Dialog Window
+  Delegates call to encapsulated window_ void Fl_Window::show() method */
+
+/** \fn void Fl_Help_Dialog::show(int argc, char **argv)
+  Shows the main Help Dialog Window
+  Delegates call to encapsulated window_ void Fl_Window::show(int argc, char **argv) instance method */
+
+/** \fn void Fl_Help_Dialog::textsize(Fl_Fontsize s)
+  Sets the internal Fl_Help_View instance text size.
+  Delegates call to encapsulated view_ void Fl_Help_View::textsize(Fl_Fontsize s) instance method */
+
+//
+// End of "$Id".
+//
diff --git a/src/Fl_Help_View.cxx b/src/Fl_Help_View.cxx
index 088f6006a..c92ff272d 100644
--- a/src/Fl_Help_View.cxx
+++ b/src/Fl_Help_View.cxx
@@ -1002,10 +1002,8 @@ Fl_Help_View::draw()
 }
 
 
-//
-// 'Fl_Help_View::find()' - Find the specified string...
-//
 
+/** Find the specified string s at starting position p, return the matching pos or -1 if not found */
 int						// O - Matching position or -1 if not found
 Fl_Help_View::find(const char *s,		// I - String to find
                    int        p)		// I - Starting position
@@ -2729,12 +2727,13 @@ void Fl_Help_View::follow_link(Fl_Help_Link *linkp)
   leftline(0);
 }
 
+/** Removes the current text selection. */
 void Fl_Help_View::clear_selection()
 {
   if (current_view==this)
     clear_global_selection();
 }
-
+/** Selects All the text in the view. */
 void Fl_Help_View::select_all()
 {
   clear_global_selection();
@@ -3007,10 +3006,10 @@ Fl_Help_View::handle(int event)	// I - Event to handle
   return (Fl_Group::handle(event));
 }
 
-//
-// 'Fl_Help_View::Fl_Help_View()' - Build a Fl_Help_View widget.
-//
-
+/** 
+  The constructor creates the Fl_Help_View widget at the specified
+  position and size.
+*/
 Fl_Help_View::Fl_Help_View(int        xx,	// I - Left position
                 	   int        yy,	// I - Top position
 			   int        ww,	// I - Width in pixels
@@ -3078,6 +3077,10 @@ Fl_Help_View::Fl_Help_View(int        xx,	// I - Left position
 //
 
 Fl_Help_View::~Fl_Help_View()
+/**
+  The destructor destroys the widget and frees all memory that has been
+  allocated for the current file.
+*/
 {
   clear_selection();
   free_data();
@@ -3090,6 +3093,7 @@ Fl_Help_View::~Fl_Help_View()
 
 int				// O - 0 on success, -1 on error
 Fl_Help_View::load(const char *f)// I - Filename to load (may also have target)
+/**  This method loads the specified file or URL.*/
 {
   FILE		*fp;		// File to read from
   long		len;		// Length of file
@@ -3211,10 +3215,7 @@ Fl_Help_View::resize(int xx,	// I - New left position
 }
 
 
-//
-// 'Fl_Help_View::topline()' - Set the top line to the named target.
-//
-
+/** Scroll the text to the indicated position,  given a named destination */
 void
 Fl_Help_View::topline(const char *n)	// I - Target name
 {
@@ -3235,10 +3236,8 @@ Fl_Help_View::topline(const char *n)	// I - Target name
 }
 
 
-//
-// 'Fl_Help_View::topline()' - Set the top line by number.
-//
 
+/** Scroll the text to the indicated position,  given a pixel line. */
 void
 Fl_Help_View::topline(int t)	// I - Top line number
 {
@@ -3260,10 +3259,9 @@ Fl_Help_View::topline(int t)	// I - Top line number
 }
 
 
-//
-// 'Fl_Help_View::leftline()' - Set the left position.
-//
 
+
+/** Sets the left position. */
 void
 Fl_Help_View::leftline(int l)	// I - Left position
 {
@@ -3283,10 +3281,7 @@ Fl_Help_View::leftline(int l)	// I - Left position
 }
 
 
-//
-// 'Fl_Help_View::value()' - Set the help text directly.
-//
-
+/** Sets the current help text buffer to the string provided and reformats the text. */
 void
 Fl_Help_View::value(const char *v)	// I - Text to view
 {
diff --git a/src/Fl_Light_Button.cxx b/src/Fl_Light_Button.cxx
index b4ca03a88..3dcfe6747 100644
--- a/src/Fl_Light_Button.cxx
+++ b/src/Fl_Light_Button.cxx
@@ -157,6 +157,11 @@ int Fl_Light_Button::handle(int event) {
   }
 }
 
+/**
+  Creates a new Fl_Light_Button widget using the given
+  position, size, and label string.
+  <P>The destructor deletes the check button.
+*/
 Fl_Light_Button::Fl_Light_Button(int X, int Y, int W, int H, const char* l)
 : Fl_Button(X, Y, W, H, l) {
   type(FL_TOGGLE_BUTTON);
diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index fbe714e58..28b6950a4 100644
--- a/src/Fl_Preferences.cxx
+++ b/src/Fl_Preferences.cxx
@@ -212,9 +212,7 @@ char Fl_Preferences::deleteEntry( const char *key )
 }
 
 
-/**
- * read an entry from the group
- */
+
 char Fl_Preferences::get( const char *key, int &value, int defaultValue )
 {
   const char *v = node->get( key );
@@ -223,9 +221,7 @@ char Fl_Preferences::get( const char *key, int &value, int defaultValue )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, int value )
 {
   sprintf( nameBuffer, "%d", value );
@@ -234,9 +230,7 @@ char Fl_Preferences::set( const char *key, int value )
 }
 
 
-/**
- * read an entry from the group
- */
+
 char Fl_Preferences::get( const char *key, float &value, float defaultValue )
 {
   const char *v = node->get( key );
@@ -245,9 +239,7 @@ char Fl_Preferences::get( const char *key, float &value, float defaultValue )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, float value )
 {
   sprintf( nameBuffer, "%g", value );
@@ -256,9 +248,7 @@ char Fl_Preferences::set( const char *key, float value )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, float value, int precision )
 {
   sprintf( nameBuffer, "%.*g", precision, value );
@@ -267,9 +257,7 @@ char Fl_Preferences::set( const char *key, float value, int precision )
 }
 
 
-/**
- * read an entry from the group
- */
+
 char Fl_Preferences::get( const char *key, double &value, double defaultValue )
 {
   const char *v = node->get( key );
@@ -278,9 +266,7 @@ char Fl_Preferences::get( const char *key, double &value, double defaultValue )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, double value )
 {
   sprintf( nameBuffer, "%g", value );
@@ -289,9 +275,7 @@ char Fl_Preferences::set( const char *key, double value )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, double value, int precision )
 {
   sprintf( nameBuffer, "%.*g", precision, value );
@@ -373,9 +357,7 @@ char Fl_Preferences::get( const char *key, char *&text, const char *defaultValue
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, const char *text )
 {
   const char *s = text ? text : "";
@@ -474,9 +456,7 @@ char Fl_Preferences::get( const char *key, void *&data, const void *defaultValue
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, const void *data, int dsize )
 {
   char *buffer = (char*)malloc( dsize*2+1 ), *d = buffer;;