doxygen comments for undocumented features in Fl_Browser_, Fl_Button, Fl_Chart.

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

4 files changed, 87 insertions, 69 deletions

diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H
index 6fc2c1bf2..ab2045f7a 100644
--- a/FL/Fl_Browser_.H
+++ b/FL/Fl_Browser_.H
@@ -43,21 +43,23 @@
 #endif
 #include "Fl_Scrollbar.H"
 
-#define FL_NORMAL_BROWSER	0
-#define FL_SELECT_BROWSER	1
-#define FL_HOLD_BROWSER		2
-#define FL_MULTI_BROWSER	3
+#define FL_NORMAL_BROWSER	0	/**< type() of Fl_Browser */
+#define FL_SELECT_BROWSER	1	/**< type() of FL_Select_Browser */
+#define FL_HOLD_BROWSER		2	/**< type() of Fl_Hold_Browser */
+#define FL_MULTI_BROWSER	3	/**< type() of Fl_Multi_Browser */
 
 /**
   This is the base for browsers.  To be useful it must be
   subclassed and several virtual functions defined.  The Forms-compatible
   browser and the file chooser's browser are subclassed off of this.
-  <P>This has been designed so that the subhas complete control
+
+  This has been designed so that the subclass has complete control
   over the storage of the data, although because next() and 
   prev() functions are used to index, it works best as a linked list
   or as a large block of characters in which the line breaks must be
-  searched for. </P>
-  <P>A great deal of work has been done so that the "height" of a data
+  searched for.
+
+  A great deal of work has been done so that the "height" of a data
   object does not need to be determined until it is drawn.  This is
   useful if actually figuring out the size of an object requires
   accessing image data or doing stat() on a file or doing some
@@ -143,13 +145,16 @@ protected:
   void bbox(int&,int&,int&,int&) const;
   int leftedge() const;	// x position after scrollbar & border
   void *find_item(int my); // item under mouse
+  
   /**
-    The first form draws the list within the normal widget bounding box.
-    
-    <P>The second form draws the contents of the browser within the
-    specified bounding box.
+    Draws the contents of the browser within the specified bounding box.
+    \todo Find the implementation, if any, and document it there!
   */
   void draw(int,int,int,int);
+  /**
+    Handles the specified event, plus 4 extra parameters!
+    \todo Find the implementation, if any, and document it there!
+  */
   int handle(int,int,int,int,int);
 
   void draw();
@@ -157,8 +162,10 @@ protected:
 
 public:
 
-  Fl_Scrollbar scrollbar;		// Vertical scrollbar
-  Fl_Scrollbar hscrollbar;		// Horizontal scrollbar
+  /** Vertical scrollbar. */
+  Fl_Scrollbar scrollbar;
+  /** Horizontal scrollbar */
+  Fl_Scrollbar hscrollbar;
 
   int handle(int);
   void resize(int,int,int,int);
@@ -188,28 +195,21 @@ public:
     disappear if the data will fit in the widget.  has_scrollbar() changes
     this based on the value of h:
   
-    <UL>
-  
-  	<LI>0 - No scrollbars.
+    \li 0 - No scrollbars.
   
-  	<LI>Fl_Browser_::HORIZONTAL - Only a horizontal
-  	scrollbar.
+    \li Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
   
-  	<LI>Fl_Browser_::VERTICAL - Only a vertical
-  	scrollbar.
+    \li Fl_Browser_::VERTICAL - Only a vertical scrollbar.
   
-  	<LI>Fl_Browser_::BOTH - The default is both
-  	scrollbars.
+    \li Fl_Browser_::BOTH - The default is both scrollbars.
   
-  	<LI>Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal
-  	scrollbar always on, vertical always off.
+    \li Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
+        vertical always off.
   
-  	<LI>Fl_Browser_::VERTICAL_ALWAYS - Vertical
-  	scrollbar always on, horizontal always off.
+    \li Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
+        horizontal always off.
   
-  	<LI>Fl_Browser_::BOTH_ALWAYS - Both always on.
-  
-    </UL>
+    \li Fl_Browser_::BOTH_ALWAYS - Both always on.
   */
   void has_scrollbar(uchar i) {has_scrollbar_ = i;}
   enum { // values for has_scrollbar()
@@ -223,45 +223,50 @@ public:
   };
 
   /**
-    The first form gets the default text font for the lines in the
-    browser.
-    
-    <P>The second form sets the default text font to font
+    Gets the default text font for the lines in the browser.
   */
   Fl_Font textfont() const {return textfont_;}
   /**
-    The first form gets the default text font for the lines in the
-    browser.
-    
-    <P>The second form sets the default text font to font
+    Sets the default text font to font \p s
   */
   void textfont(Fl_Font s) {textfont_ = s;}
+
   /**
-    The first form gets the default text size for the lines in the
-    browser.
-    
-    <P>The second form sets the default text size to size
+    Gets the default text size for the lines in the browser.
   */
   Fl_Fontsize textsize() const {return textsize_;}
+  /**
+    Sets the default text size to size \p s.
+  */
   void textsize(Fl_Fontsize s) {textsize_ = s;}
+
   /**
-    The first form gets the default text color for the lines in the
-    browser.
-    
-    <P>The second form sets the default text color to color
+    Gets the default text color for the lines in the browser.
   */
   Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+  /**
+    Sets the default text color to color \p n.
+  */
   void textcolor(unsigned n) {textcolor_ = n;}
 
-  /**    Sets or gets the width of any scrollbars that are used.  */
-  static void scrollbar_width(int b) {scrollbar_width_ = b;}
-  /**    Sets or gets the width of any scrollbars that are used.  */
+  /**
+    Gets the width of any scrollbars that are used.
+  */
   static int scrollbar_width() {return scrollbar_width_;}
+  /**
+    Sets the width of any scrollbars that are used to \p b.
+  */
+  static void scrollbar_width(int b) {scrollbar_width_ = b;}
 
-  // for back compatibility:
-  /**    This method moves the vertical scrollbar to the righthand side of the list.  */
+  /**
+    Moves the vertical scrollbar to the righthand side of the list.
+    For back compatibility.
+  */
   void scrollbar_right() {scrollbar.align(FL_ALIGN_RIGHT);}
-  /**    This method moves the vertical scrollbar to the lefthand side of the list.  */
+  /**
+    Moves the vertical scrollbar to the lefthand side of the list.
+    For back compatibility.
+  */
   void scrollbar_left() {scrollbar.align(FL_ALIGN_LEFT);}
 
 };
diff --git a/FL/Fl_Chart.H b/FL/Fl_Chart.H
index f57d9ab38..6f95b23ba 100644
--- a/FL/Fl_Chart.H
+++ b/FL/Fl_Chart.H
@@ -36,23 +36,24 @@
 #endif
 
 // values for type()
-#define FL_BAR_CHART		0
-#define FL_HORBAR_CHART		1
-#define FL_LINE_CHART		2
-#define FL_FILL_CHART		3
-#define FL_SPIKE_CHART		4
-#define FL_PIE_CHART		5
-#define FL_SPECIALPIE_CHART	6
+#define FL_BAR_CHART		0	/**< type() for Bar Chart variant */
+#define FL_HORBAR_CHART		1	/**< type() for Horizontal Bar Chart variant */
+#define FL_LINE_CHART		2	/**< type() for Line Chart variant */
+#define FL_FILL_CHART		3	/**< type() for Fill Line Chart variant */
+#define FL_SPIKE_CHART		4	/**< type() for Spike Chart variant */
+#define FL_PIE_CHART		5	/**< type() for Pie Chart variant */
+#define FL_SPECIALPIE_CHART	6	/**< type() for Special Pie Chart variant */
 
-#define FL_FILLED_CHART  FL_FILL_CHART	// compatibility
+#define FL_FILLED_CHART  FL_FILL_CHART	/**< for compatibility */
 
-#define FL_CHART_MAX		128
-#define FL_CHART_LABEL_MAX	18
+#define FL_CHART_MAX		128	/**< max entries per chart */
+#define FL_CHART_LABEL_MAX	18	/**< max label length for entry */
 
+/** For internal use only */
 struct FL_CHART_ENTRY {
-   float val;
-   unsigned col;
-   char str[FL_CHART_LABEL_MAX+1];
+   float val;				/**< For internal use only. */
+   unsigned col;			/**< For internal use only. */
+   char str[FL_CHART_LABEL_MAX+1];	/**< For internal use only. */
 };
 
 /**
@@ -118,17 +119,25 @@ public:
     void size(int W, int H) { Fl_Widget::size(W, H); }
 
     /**
-      Get the maximum number of data values for a chart.
+      Gets the maximum number of data values for a chart.
      */
     int maxsize() const {return maxnumb;}
 
     void maxsize(int m);
 
+    /** Gets the chart's text font */
     Fl_Font textfont() const {return textfont_;}
+    /** Sets the chart's text font to \p s. */
     void textfont(Fl_Font s) {textfont_ = s;}
+
+    /** Gets the chart's text size */
     Fl_Fontsize textsize() const {return textsize_;}
+    /** gets the chart's text size to \p s. */
     void textsize(Fl_Fontsize s) {textsize_ = s;}
+
+    /** Gets the chart's text color */
     Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+    /** gets the chart's text color to \p n. */
     void textcolor(unsigned n) {textcolor_ = n;}
 
     /**
diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx
index 13812731a..d1f83882f 100644
--- a/src/Fl_Browser_.cxx
+++ b/src/Fl_Browser_.cxx
@@ -333,10 +333,7 @@ void Fl_Browser_::display(void* p) {
 // redraw, has side effect of updating top and setting scrollbar:
 
 /**
-  The first form draws the list within the normal widget bounding box.
-  
-  <P>The second form draws the contents of the browser within the
-  specified bounding box.
+  Draws the list within the normal widget bounding box.
 */
 void Fl_Browser_::draw() {
   int drawsquare = 0;
@@ -542,6 +539,9 @@ void Fl_Browser_::replacing(void* a, void* b) {
   if (a == max_width_item) {max_width_item = 0; max_width = 0;}
 }
 
+/**
+  Exchange pointers \p a and \p b.
+*/
 void Fl_Browser_::swapping(void* a, void* b) {
   redraw_line(a);
   redraw_line(b);
diff --git a/src/fl_shortcut.cxx b/src/fl_shortcut.cxx
index dd1d9b9d0..4f67464ab 100644
--- a/src/fl_shortcut.cxx
+++ b/src/fl_shortcut.cxx
@@ -202,6 +202,10 @@ const char * fl_shortcut_label(int shortcut) {
 
 // Emulation of XForms named shortcuts
 #include <stdlib.h>
+/**
+  Emulation of XForms named shortcuts.
+  \todo Why does doxygen display fl_old_shortcut() on Fl_Button page?
+*/
 int fl_old_shortcut(const char* s) {
   if (!s || !*s) return 0;
   int n = 0;