Doxygen Documentation WP4 Done. Has all documentation content but should be completed in increment 2. Registered for WP5.

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

8 files changed, 119 insertions, 56 deletions

diff --git a/src/Fl_Dial.cxx b/src/Fl_Dial.cxx
index 3b76460d6..0426f55b3 100644
--- a/src/Fl_Dial.cxx
+++ b/src/Fl_Dial.cxx
@@ -135,7 +135,11 @@ int Fl_Dial::handle(int e) {
 }
 
 Fl_Dial::Fl_Dial(int X, int Y, int W, int H, const char* l)
-  : Fl_Valuator(X, Y, W, H, l) {
+/**
+  Creates a new Fl_Dial widget using the given position, size,
+  and label string. The default type is FL_NORMAL_DIAL.
+*/
+: Fl_Valuator(X, Y, W, H, l) {
   box(FL_OVAL_BOX);
   selection_color(FL_INACTIVE_COLOR); // was 37
   a1 = 45;
diff --git a/src/Fl_File_Icon.cxx b/src/Fl_File_Icon.cxx
index fa453c5dd..6ac6438b3 100644
--- a/src/Fl_File_Icon.cxx
+++ b/src/Fl_File_Icon.cxx
@@ -81,11 +81,11 @@
 Fl_File_Icon	*Fl_File_Icon::first_ = (Fl_File_Icon *)0;
 
 
-//
-// 'Fl_File_Icon::Fl_File_Icon()' - Create a new file icon.
-//
-
-Fl_File_Icon::Fl_File_Icon(const char *p,	/* I - Filename pattern */
+/**
+  The constructor creates a new Fl_File_Icon with the specified
+  information.
+*/
+Fl_File_Icon::Fl_File_Icon(const char *p,	/**< I - Filename pattern */
                 	   int        t,	/* I - File type */
 			   int        nd,	/* I - Number of data values */
 			   short      *d)	/* I - Data values */
@@ -114,12 +114,11 @@ Fl_File_Icon::Fl_File_Icon(const char *p,	/* I - Filename pattern */
 }
 
 
-//
-// 'Fl_File_Icon::~Fl_File_Icon()' - Remove a file icon.
-//
-
-Fl_File_Icon::~Fl_File_Icon()
-{
+/**
+  The destructor destroys the icon and frees all memory that has been
+  allocated for it.
+*/
+Fl_File_Icon::~Fl_File_Icon() {
   Fl_File_Icon	*current,	// Current icon in list
 		*prev;		// Previous icon in list
 
@@ -144,10 +143,7 @@ Fl_File_Icon::~Fl_File_Icon()
 }
 
 
-//
-// 'Fl_File_Icon::add()' - Add data to an icon.
-//
-
+/** Adds a keyword value to the icon array, returning a pointer to it.*/
 short *				// O - Pointer to new data value
 Fl_File_Icon::add(short d)	// I - Data to add
 {
@@ -178,10 +174,7 @@ Fl_File_Icon::add(short d)	// I - Data to add
 }
 
 
-//
-// 'Fl_File_Icon::find()' - Find an icon based upon a given file.
-//
-
+/** Finds an icon that matches the given filename and file type.*/
 Fl_File_Icon *				// O - Matching file icon or NULL
 Fl_File_Icon::find(const char *filename,// I - Name of file */
                    int        filetype)	// I - Enumerated file type
@@ -243,11 +236,7 @@ Fl_File_Icon::find(const char *filename,// I - Name of file */
   return (current);
 }
 
-
-//
-// 'Fl_File_Icon::draw()' - Draw an icon.
-//
-
+/** Drawsan icon. */
 void
 Fl_File_Icon::draw(int      x,		// I - Upper-lefthand X
         	   int      y,		// I - Upper-lefthand Y
@@ -446,13 +435,11 @@ Fl_File_Icon::draw(int      x,		// I - Upper-lefthand X
   fl_pop_matrix();
 }
 
-
-//
-// 'Fl_File_Icon::label()' - Set the widget's label to an icon.
-//
-
-void
-Fl_File_Icon::label(Fl_Widget *w)	// I - Widget to label
+/**
+  Applies the icon to the widget, registering the Fl_File_Icon
+  label type as needed.
+*/
+void Fl_File_Icon::label(Fl_Widget *w)	// I - Widget to label
 {
   Fl::set_labeltype(_FL_ICON_LABEL, labeltype, 0);
   w->label(_FL_ICON_LABEL, (const char*)this);
diff --git a/src/Fl_File_Icon2.cxx b/src/Fl_File_Icon2.cxx
index 7ab1bda72..303c0e1f5 100644
--- a/src/Fl_File_Icon2.cxx
+++ b/src/Fl_File_Icon2.cxx
@@ -98,10 +98,7 @@ static char	*get_kde_val(char *str, const char *key);
 static const char *kdedir = NULL;
 
 
-//
-// 'Fl_File_Icon::load()' - Load an icon file...
-//
-
+/** Loads the specified icon image. The format is deduced from the filename.*/
 void
 Fl_File_Icon::load(const char *f)	// I - File to read from
 {
@@ -124,10 +121,7 @@ Fl_File_Icon::load(const char *f)	// I - File to read from
 }
 
 
-//
-// 'Fl_File_Icon::load_fti()' - Load an SGI-format FTI file...
-//
-
+/** Loads an SGI icon file.*/
 int					// O - 0 on success, non-zero on error
 Fl_File_Icon::load_fti(const char *fti)	// I - File to read from
 {
@@ -341,12 +335,8 @@ Fl_File_Icon::load_fti(const char *fti)	// I - File to read from
 }
 
 
-//
-// 'Fl_File_Icon::load_image()' - Load an image icon file...
-//
-
-int					// O - 0 on success, non-0 on error
-Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
+/** Load an image icon file from an image filename. Returns  0 on success, non-0 on error. */
+int Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
 {
   Fl_Shared_Image	*img;		// Image file
 
@@ -587,9 +577,14 @@ Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
 }
 
 
-//
-// 'Fl_File_Icon::load_system_icons()' - Load the standard system icons/filetypes.
-
+/**  Loads all system-defined icons. This call is useful when using the
+  FileChooser widget and should be used when the application
+  starts:
+  
+  <UL><PRE>
+  Fl_File_Icon::load_system_icons();
+  </PRE></UL>
+*/
 void
 Fl_File_Icon::load_system_icons(void) {
   int		i;		// Looping var
diff --git a/src/Fl_Pack.cxx b/src/Fl_Pack.cxx
index 957f28544..8a1607250 100644
--- a/src/Fl_Pack.cxx
+++ b/src/Fl_Pack.cxx
@@ -34,6 +34,16 @@
 #include <FL/Fl_Pack.H>
 #include <FL/fl_draw.H>
 
+/**
+  Creates a new Fl_Pack widget using the given position, size,
+  and label string. The default boxtype is FL_NO_BOX.
+  <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_Pack and all of it's children can be automatic (local)
+  variables, but you must declare the Fl_Pack<I>first</I>, so
+  that it is destroyed last.
+*/
 Fl_Pack::Fl_Pack(int X, int Y, int W, int H,const char *l)
 : Fl_Group(X, Y, W, H, l) {
   resizable(0);
diff --git a/src/Fl_Positioner.cxx b/src/Fl_Positioner.cxx
index a960f707c..1cb0bd7a1 100644
--- a/src/Fl_Positioner.cxx
+++ b/src/Fl_Positioner.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 
+
 // The positioner widget from Forms, gives 2D input
 // Written by: Mark Overmars
 
@@ -56,6 +57,7 @@ void Fl_Positioner::draw() {
   draw_label();
 }
 
+/** Returns the current position in x and y.*/
 int Fl_Positioner::value(double X, double Y) {
   clear_changed();
   if (X == xvalue_ && Y == yvalue_) return 0;
@@ -64,10 +66,12 @@ int Fl_Positioner::value(double X, double Y) {
   return 1;
 }
 
+/** Sets the X axis coordinate.*/
 int Fl_Positioner::xvalue(double X) {
   return(value(X, yvalue_));
 }
 
+/** Sets the Y axis coordinate.*/
 int Fl_Positioner::yvalue(double Y) {
   return(value(xvalue_, Y));
 }
@@ -120,6 +124,10 @@ int Fl_Positioner::handle(int e) {
   return handle(e, x(), y(), w(), h());
 }
 
+/**
+  Creates a new Fl_Positioner widget using the given position,
+  size, and label string. The default boxtype is FL_NO_BOX.
+*/
 Fl_Positioner::Fl_Positioner(int X, int Y, int W, int H, const char* l)
 : Fl_Widget(X, Y, W, H, l) {
   box(FL_DOWN_BOX);
@@ -132,6 +140,7 @@ Fl_Positioner::Fl_Positioner(int X, int Y, int W, int H, const char* l)
   xstep_ = ystep_ = 0;
 }
 
+/** Sets the X axis bounds.*/
 void Fl_Positioner::xbounds(double a, double b) {
   if (a != xmin || b != xmax) {
     xmin = a; xmax = b;
@@ -139,6 +148,7 @@ void Fl_Positioner::xbounds(double a, double b) {
   }
 }
 
+/** Sets the Y axis bounds.*/
 void Fl_Positioner::ybounds(double a, double b) {
   if (a != ymin || b != ymax) {
     ymin = a; ymax = b;
diff --git a/src/Fl_Tabs.cxx b/src/Fl_Tabs.cxx
index 7260de4df..623e3d3cf 100644
--- a/src/Fl_Tabs.cxx
+++ b/src/Fl_Tabs.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 
+
 // This is the "file card tabs" interface to allow you to put lots and lots
 // of buttons and switches in a panel, as popularized by many toolkits.
 
@@ -248,10 +249,13 @@ int Fl_Tabs::push(Fl_Widget *o) {
   return 1;
 }
 
-// The value() is the first visible child (or the last child if none
-// are visible) and this also hides any other children.
-// This allows the tabs to be deleted, moved to other groups, and
-// show()/hide() called without it screwing up.
+/**  
+   Gets the currently visible widget/tab.
+   The value() is the first visible child (or the last child if none
+   are visible) and this also hides any other children.
+   This allows the tabs to be deleted, moved to other groups, and
+   show()/hide() called without it screwing up.
+*/
 Fl_Widget* Fl_Tabs::value() {
   Fl_Widget* v = 0;
   Fl_Widget*const* a = array();
@@ -264,8 +268,11 @@ Fl_Widget* Fl_Tabs::value() {
   return v;
 }
 
-// Setting the value hides all other children, and makes this one
-// visible, iff it is really a child:
+/**
+  Sets the widget to become the current visible widget/tab.
+  Setting the value hides all other children, and makes this one
+  visible, if it is really a child.
+*/
 int Fl_Tabs::value(Fl_Widget *newvalue) {
   Fl_Widget*const* a = array();
   int ret = 0;
@@ -391,6 +398,23 @@ void Fl_Tabs::draw_tab(int x1, int x2, int W, int H, Fl_Widget* o, int what) {
   fl_draw_shortcut = prev_draw_shortcut;
 }
 
+/**
+    Creates a new Fl_Tabs widget using the given position, size,
+    and label string. The default boxtype is FL_THIN_UP_BOX.
+
+    <P>Use add(Fl_Widget
+    *) to add each child, which are usually
+    Fl_Group widgets. The children should be sized to stay
+    away from the top or bottom edge of the Fl_Tabs widget,
+    which is where the tabs will be drawn.
+
+    <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_Tabs and all of it's children
+    can be automatic (local) variables, but you must declare the
+    Fl_Tabs widget <I>first</I> so that it is destroyed last.
+*/
 Fl_Tabs::Fl_Tabs(int X,int Y,int W, int H, const char *l) :
   Fl_Group(X,Y,W,H,l)
 {
diff --git a/src/Fl_Tile.cxx b/src/Fl_Tile.cxx
index ca94ffae0..35241f125 100644
--- a/src/Fl_Tile.cxx
+++ b/src/Fl_Tile.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 
+
 // Group of 2 or 4 "tiles" that can be resized by dragging border
 // The size of the first child determines where the resize border is.
 // The resizebox is used to limit where the border can be dragged to.
@@ -36,7 +37,10 @@
 
 // Drag the edges that were initially at oldx,oldy to newx,newy:
 // pass zero as oldx or oldy to disable drag in that direction:
-
+/** 
+  Drag the intersection at from_x,from_y to to_x,to_y.
+  This redraws all the necessary children.
+*/
 void Fl_Tile::position(int oix, int oiy, int newx, int newy) {
   Fl_Widget*const* a = array();
   int *p = sizes();
diff --git a/src/forms_free.cxx b/src/forms_free.cxx
index 5855f8b09..918086d79 100644
--- a/src/forms_free.cxx
+++ b/src/forms_free.cxx
@@ -41,6 +41,34 @@ void Fl_Free::step(void *v) {
   Fl::add_timeout(.01,step,v);
 }
 
+/**
+    The constructor takes both the type and the handle
+    function. The handle function should be declared as follows:
+    <UL>
+    <PRE>
+    int
+    handle_function(Fl_Widget *w,
+                   int       event,
+    	        float     event_x,
+    		float     event_y,
+    		char      key)
+    </PRE>
+    </UL>
+    This function is called from the the handle() method in
+    response to most events, and is called by the draw() method.
+    The event argument contains the event type:
+    <UL>
+    <PRE>
+    // old event names for compatability:
+    #define FL_MOUSE		FL_DRAG
+    #define FL_DRAW			0
+    #define FL_STEP			9
+    #define FL_FREEMEM		12
+    #define FL_FREEZE		FL_UNMAP
+    #define FL_THAW			FL_MAP
+    </PRE>
+    </UL>
+*/
 Fl_Free::Fl_Free(uchar t,int X, int Y, int W, int H,const char *l,
 		 FL_HANDLEPTR hdl) :
 Fl_Widget(X,Y,W,H,l) {
@@ -51,6 +79,7 @@ Fl_Widget(X,Y,W,H,l) {
     Fl::add_timeout(.01,step,this);
 }
 
+/** The destructor will call the handle function with the event FL_FREE_MEM. */
 Fl_Free::~Fl_Free() {
   Fl::remove_timeout(step,this);
   hfunc(this,FL_FREEMEM,0,0,0);