o Major mods to Fl_Browser_.{cxx.H}'s doxygen docs

	o Small mods to Fl_Browser.{cxx,H}'s doxygen docs
	o FL_SORT_ASC/DESC -> FL_SORT_ASCENDING/DESCENDING (includes necessary mod to test/browser.cxx demo)

	TODO: Fl_Browser needs new '\see Related methods: ' that was initiated in Fl_Browser_



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

5 files changed, 401 insertions, 281 deletions

diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H
index fd0446fca..4bd8cf617 100644
--- a/FL/Fl_Browser.H
+++ b/FL/Fl_Browser.H
@@ -139,46 +139,61 @@ public:
   void swap(int a, int b);
   void clear();
 
-  /** Returns how many lines are in the browser.
-      The last line number is equal to this.
-      Returns 0 if browser is empty.
+  /**
+    Returns how many lines are in the browser.
+    The last line number is equal to this.
+    Returns 0 if browser is empty.
   */
-  int size() const {return lines;}
+  int size() const { return lines; }
   void size(int W, int H) { Fl_Widget::size(W, H); }
 
   int topline() const ;
   /** For internal use only? */
   enum Fl_Line_Position { TOP, BOTTOM, MIDDLE };
   void lineposition(int line, Fl_Line_Position pos);
-  /** Scrolls the browser so the top item in the browser is showing the specified \p line. */
+  /**
+    Scrolls the browser so the top item in the browser
+    is showing the specified \p line.
+    \param[in] line The line to be displayed at the top.
+   */
   void topline(int line) { lineposition(line, TOP); }
-  /** Scrolls the browser so the bottom item in the browser is showing the specified \p line. */
+  /**
+    Scrolls the browser so the bottom item in the browser
+    is showing the specified \p line.
+    \param[in] line The line to be displayed at the bottom.
+   */
   void bottomline(int line) { lineposition(line, BOTTOM); }
-  /** Scrolls the browser so the middle item in the browser is showing the specified \p line. */
+  /**
+    Scrolls the browser so the middle item in the browser
+    is showing the specified \p line.
+    \param[in] line The line to be displayed in the middle.
+   */
   void middleline(int line) { lineposition(line, MIDDLE); }
 
   int select(int line, int val=1);
   int selected(int line) const ;
   void show(int line);
   /** Shows the entire Fl_Browser widget -- opposite of hide(). */
-  void show() {Fl_Widget::show();}
+  void show() { Fl_Widget::show(); }
   void hide(int line);
   /** Hides the entire Fl_Browser widget -- opposite of show(). */
-  void hide() {Fl_Widget::hide();}
+  void hide() { Fl_Widget::hide(); }
   int visible(int line) const ;
 
   int value() const ;
   /** Sets the browser's value(), which selects the specified \p line.
       This is the same as calling select(line).
    */
-  void value(int line) { select(line);}
+  void value(int line) { select(line); }
   const char* text(int line) const ;
   void text(int line, const char* newtext);
   void* data(int line) const ;
   void data(int line, void* d);
 
   Fl_Browser(int X, int Y, int W, int H, const char *L = 0);
-  /** The destructor deletes all list items and destroys the browser. */
+  /**
+    The destructor deletes all list items and destroys the browser.
+   */
   ~Fl_Browser() { clear(); }
 
   /**
@@ -210,24 +225,24 @@ public:
     <tt>sprintf("\@C%d\@.%s", color, string)</tt> and it will work even if the
     string starts with a digit or has the format character in it.
   */
-  char format_char() const {return format_char_;}
+  char format_char() const { return format_char_; }
   /**
     Sets the current format code prefix character to \p c.
     The default prefix is '\@'.  Set the prefix to 0 to disable formatting.
     \see uchar Fl_Browser::format_char() const
   */
-  void format_char(char c) {format_char_ = c;}
+  void format_char(char c) { format_char_ = c; }
   /**
     Gets the current column separator character.
     The default is '\\t' (tab).
   */
-  char column_char() const {return column_char_;}
+  char column_char() const { return column_char_; }
   /**
     Sets the column separator to c.
     This will only have an effect if you also set column_widths().
     The default is '\\t' (tab).
   */
-  void column_char(char c) {column_char_ = c;}
+  void column_char(char c) { column_char_ = c; }
   /**
     Gets the current column width array.
     This array is zero-terminated and specifies the widths in pixels of
@@ -250,17 +265,17 @@ public:
   [..]
     \endcode
   */
-  const int* column_widths() const {return column_widths_;}
+  const int* column_widths() const { return column_widths_; }
   /**
     Sets the current array to \p arr.  Make sure the last entry is zero.
     \see const int *Fl_Browser::column_widths() const
   */
-  void column_widths(const int* arr) {column_widths_ = arr;}
+  void column_widths(const int* arr) { column_widths_ = arr; }
 
   /**
     Returns non-zero if \p line is visible.
   */
-  int displayed(int line) const {return Fl_Browser_::displayed(find_line(line));}
+  int displayed(int line) const { return Fl_Browser_::displayed(find_line(line)); }
 
   /**
     Make the item at the specified \p line visible().
@@ -276,7 +291,7 @@ public:
   }
 
   /** For back compatibility only. */
-  void replace(int a, const char* b) {text(a, b);}
+  void replace(int a, const char* b) { text(a, b); }
   void display(int line, int val=1);
 };
 
diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H
index 22a9a03f6..0d150bdd9 100644
--- a/FL/Fl_Browser_.H
+++ b/FL/Fl_Browser_.H
@@ -28,11 +28,6 @@
 /* \file
    Fl_Browser_ widget . */
 
-// This is the base class for browsers.  To be useful it must
-// be subclassed and several virtual functions defined.  The
-// Forms-compatable browser and the file chooser's browser are
-// subclassed off of this.
-
 // Yes, I know this should be a template...
 
 #ifndef Fl_Browser__H
@@ -48,11 +43,11 @@
 #define FL_HOLD_BROWSER		2	/**< type() of Fl_Hold_Browser */
 #define FL_MULTI_BROWSER	3	/**< type() of Fl_Multi_Browser */
 
-#define FL_SORT_ASC		0	/**< sort browser items in ascending alphabetic order. */
-#define FL_SORT_DESC		1	/**< sort in descending order */
+#define FL_SORT_ASCENDING	0	/**< sort browser items in ascending alphabetic order. */
+#define FL_SORT_DESCENDING	1	/**< sort in descending order */
 
 /**
-  This is the base for browsers.  To be useful it must be
+  This is the base class 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.
 
@@ -91,211 +86,237 @@ class FL_EXPORT Fl_Browser_ : public Fl_Group {
 protected:
 
   // All of the following must be supplied by the subclass:
-  /** This method must be provided by the subclass to return the first item in  the list. */
-    virtual void *item_first() const = 0;
-  /** This method must be provided by the subclass to return the item in the list after p. */
-    virtual void *item_next(void *) const = 0;
-  /** This method must be provided by the subclass to return the item in the list before p. */
-    virtual void *item_prev(void *) const = 0;
-  /** This method can be provided by the subclass to return the ilast item in the list. */
-    virtual void *item_last() const { return 0L; }
+  /**
+    This method must be provided by the subclass 
+    to return the first item in the list.
+    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+   */
+  virtual void *item_first() const = 0;
+  /**
+    This method must be provided by the subclass
+    to return the item in the list after \p item.
+    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+   */
+  virtual void *item_next(void *item) const = 0;
+  /**
+    This method must be provided by the subclass
+    to return the item in the list before \p item.
+    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+   */
+  virtual void *item_prev(void *item) const = 0;
+  /**
+    This method must be provided by the subclass
+    to return the last item in the list.
+    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+   */
+  virtual void *item_last() const { return 0L; }
   /** 
-    This method must be provided by the subclass to return the height of the
-    item p in pixels.  Allow for two additional pixels for the list
-    selection box.
+    This method must be provided by the subclass to return 
+    the height of \p item in pixels.
+    Allow for two additional pixels for the list selection box.
+    \param[in] item The item whose height is returned.
+    \returns The height of the specified \p item in pixels.
+    \see Related methods: item_height(), item_width(), item_quick_height()
   */
-  virtual int item_height(void *) const = 0;
+  virtual int item_height(void *item) const = 0;
   /**
     This method must be provided by the subclass to return the width of the
-    item p in pixels.  Allow for two additional pixels for the list
+    \p item in pixels.  Allow for two additional pixels for the list
     selection box.
+    \param[in] item The item whose width is returned.
+    \returns The width of the item in pixels.
   */
-  virtual int item_width(void *) const = 0;
-  virtual int item_quick_height(void *) const ;
+  virtual int item_width(void *item) const = 0;
+  virtual int item_quick_height(void *item) const ;
   /**
-    This method must be provided by the subclass to draw the item
-    p in the area indicated by x, y, w,
-    and h.
+    This method must be provided by the subclass to draw the \p item
+    in the area indicated by \p X, \p Y, \p W, \p H.
   */
-  virtual void item_draw(void *,int,int,int,int) const = 0;
+  virtual void item_draw(void *item,int X,int Y,int W,int H) const = 0;
   /**
-    This optional function returns a string that may be used for sorting. 
+    This optional method returns a string (label) that may be used for sorting. 
+    \param[in] item The item whose label text is returned.
+    \returns The item's text label. (Can be NULL if blank)
    */
   virtual const char *item_text(void *item) const { return 0L; }
   /**
-    This optional function is required for sorting browser items.
+    This optional method should be provided by the subclass 
+    to efficiently swap browser items \p a and \p b, such as for sorting.
+    \param[in] a,b The two items to be swapped.
    */
-  virtual void item_swap(void*, void*) { }
+  virtual void item_swap(void *a,void *b) { }
   /**
-    Return the item a specified index. 
+    This method must be provided by the subclass 
+    to return the item for the specified \p index. 
+    \param[in] index The \p index of the item to be returned
+    \returns The item at the specified \p index.
    */
-  virtual void *item_at(int) const { return 0L; }
+  virtual void *item_at(int index) const { return 0L; }
   // you don't have to provide these but it may help speed it up:
   virtual int full_width() const ;	// current width of all items
   virtual int full_height() const ;	// current height of all items
   virtual int incr_height() const ;	// average height of an item
   // These only need to be done by subclass if you want a multi-browser:
-  virtual void item_select(void *,int=1);
-  virtual int item_selected(void *) const ;
+  virtual void item_select(void *item,int val=1);
+  virtual int item_selected(void *item) const ;
 
   // things the subclass may want to call:
-  /**  Returns the item the appears at the top of the list.  */
-  void *top() const {return top_;}
+  /**
+    Returns the item that appears at the top of the list.
+   */
+  void *top() const { return top_; }
   /**
     Returns the item currently selected, or NULL if there is no selection.
     
-    <P>For multiple selection browsers this call returns the currently focused item,
+    For multiple selection browsers this call returns the currently focused item,
     even if it is not selected. To find all selected items, call 
-    
     Fl_Multi_Browser::selected() for every item in question.
   */
-  void *selection() const {return selection_;}
+  void *selection() const { return selection_; }
   void new_list(); // completely clobber all data, as though list replaced
-  void deleting(void *a); // get rid of any pointers to a
+  void deleting(void *item); // get rid of any pointers to item
   void replacing(void *a,void *b); // change a pointers to b
   void swapping(void *a,void *b); // exchange pointers a and b
   void inserting(void *a,void *b); // insert b near a
-  int displayed(void *) const ; // true if this line is visible
-  void redraw_line(void *); // minimal update, no change in size
-  /**    This method will cause the entire list to be redrawn.  */
-  void redraw_lines() {damage(FL_DAMAGE_SCROLL);} // redraw all of them
-  void bbox(int&,int&,int&,int&) const;
+  int displayed(void *item) const ; // true if this item is visible
+  void redraw_line(void *item); // minimal update, no change in size
+  /**
+    This method will cause the entire list to be redrawn.
+    \see Related methods: redraw_lines(), redraw_line()
+   */
+  void redraw_lines() { damage(FL_DAMAGE_SCROLL); } // redraw all of them
+  void bbox(int &X,int &Y,int &W,int &H) const;
   int leftedge() const;	// x position after scrollbar & border
-  void *find_item(int my); // item under mouse
+  void *find_item(int ypos); // item under mouse
   
-  /**
-    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!
-    fabien: I guess the answer is there is no implementation (yet?), 
-       so let's comment out this method that does not exist.
-  int handle(int,int,int,int,int);
-  */
-
   void draw();
-  Fl_Browser_(int,int,int,int,const char * = 0);
+  Fl_Browser_(int X,int Y,int W,int H,const char *L=0);
 
 public:
 
-  /** Vertical scrollbar. */
+  /**
+    Vertical scrollbar. Public, so that it can be accessed directly.
+   */
   Fl_Scrollbar scrollbar;
-  /** Horizontal scrollbar */
+  /**
+    Horizontal scrollbar. Public, so that it can be accessed directly.
+   */
   Fl_Scrollbar hscrollbar;
 
-  int handle(int);
-  void resize(int,int,int,int);
+  int handle(int event);
+  void resize(int X,int Y,int W,int H);
 
-  int select(void *,int=1,int docallbacks=0);
-  int select_only(void *,int docallbacks=0);
+  int select(void *item,int val=1,int docallbacks=0);
+  int select_only(void *item,int docallbacks=0);
   int deselect(int docallbacks=0);
   /**
-    Gets or sets the vertical scrolling position of the list,
-    which is the pixel offset of the list items within the list
-    area.
+    Gets the vertical scroll position of the list as a pixel position \p pos.
+    The position returned is how many pixels of the list are scrolled off the top edge
+    of the screen.  Example: A position of '3' indicates the top 3 pixels of 
+    the list are scrolled off the top edge of the screen.
+    \see Related methods: position(), hposition()
   */
-  int position() const {return position_;}
+  int position() const { return position_; }
+  void position(int pos); // scroll to here
   /**
-    Gets or sets the horizontal scrolling position of the list,
-    which is the pixel offset of the list items within the list
-    area.
+    Gets the horizontal scroll position of the list as a pixel position \p pos.
+    The position returned is how many pixels of the list are scrolled off the left edge
+    of the screen. Example: A position of '18' indicates the left 18 pixels of
+    the list are scrolled off the left edge of the screen.
+    \see Related methods: position(), hposition()
   */
-  int hposition() const {return hposition_;}
-  void position(int); // scroll to here
+  int hposition() const { return hposition_; }
   void hposition(int); // pan to here
-  void display(void*); // scroll so this item is shown
-  /** See Fl_Browser_::has_scrollbar(uchar) */
-  uchar has_scrollbar() const {return has_scrollbar_;}
+  void display(void *item); // scroll so this item is shown
+
   /**
+    Values for has_scrollbar().
+   */
+  enum { // values for has_scrollbar()
+    HORIZONTAL = 1,		///< Only show horizontal scrollbar
+    VERTICAL = 2,		///< Only show vertical scrollbar
+    BOTH = 3,			///< Show both scrollbars (default)
+    ALWAYS_ON = 4,		///< Both scrollbars always on
+    HORIZONTAL_ALWAYS = 5,	///< horizontal scrollbar always on
+    VERTICAL_ALWAYS = 6,	///< vertical scrollbar always on
+    BOTH_ALWAYS = 7		///< both scrollbars always on
+  };
+  /**
+    Returns the current scrollbar mode, see Fl_Browser_::has_scrollbar(uchar)
+   */
+  uchar has_scrollbar() const { return has_scrollbar_; }
+  /**
+    Sets whether the widget should have scrollbars or not (default Fl_Browser_::BOTH).
     By default you can scroll in both directions, and the scrollbars
-    disappear if the data will fit in the widget.  has_scrollbar() changes
-    this based on the value of h:
-  
-    \li 0 - No scrollbars.
-  
-    \li Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
-  
-    \li Fl_Browser_::VERTICAL - Only a vertical scrollbar.
-  
-    \li Fl_Browser_::BOTH - The default is both scrollbars.
-  
-    \li Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
-        vertical always off.
-  
-    \li Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
-        horizontal always off.
+    disappear if the data will fit in the widget.  
+    has_scrollbar() changes this based on the value of \p mode:
   
-    \li Fl_Browser_::BOTH_ALWAYS - Both always on.
+    - 0 - No scrollbars.
+
+    - Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
+
+    - Fl_Browser_::VERTICAL - Only a vertical scrollbar.
+
+    - Fl_Browser_::BOTH - The default is both scrollbars.
+
+    - Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
+      vertical always off.
+
+    - Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
+      horizontal always off.
+
+    - Fl_Browser_::BOTH_ALWAYS - Both always on.
   */
-  void has_scrollbar(uchar i) {has_scrollbar_ = i;}
-  enum { // values for has_scrollbar()
-    HORIZONTAL = 1,
-    VERTICAL = 2,
-    BOTH = 3,
-    ALWAYS_ON = 4,
-    HORIZONTAL_ALWAYS = 5,
-    VERTICAL_ALWAYS = 6,
-    BOTH_ALWAYS = 7
-  };
+  void has_scrollbar(uchar mode) { has_scrollbar_ = mode; }
 
   /**
     Gets the default text font for the lines in the browser.
+    \see Related methods: textfont(), textsize(), textcolor()
   */
-  Fl_Font textfont() const {return textfont_;}
+  Fl_Font textfont() const { return textfont_; }
   /**
-    Sets the default text font to font \p s
+    Sets the default text font for the lines in the browser to \p font.
   */
-  void textfont(Fl_Font s) {textfont_ = s;}
+  void textfont(Fl_Font font) { textfont_ = font; }
 
   /**
-    Gets the default text size for the lines in the browser.
+    Gets the default text size (in pixels) for the lines in the browser.
   */
-  Fl_Fontsize textsize() const {return textsize_;}
+  Fl_Fontsize textsize() const { return textsize_; }
   /**
-    Sets the default text size to size \p s.
+    Sets the default text size (in pixels) for the lines in the browser to \p size.
   */
-  void textsize(Fl_Fontsize s) {textsize_ = s;}
+  void textsize(Fl_Fontsize size) { textsize_ = size; }
 
   /**
     Gets the default text color for the lines in the browser.
   */
-  Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+  Fl_Color textcolor() const { return (Fl_Color)textcolor_; }
   /**
-    Sets the default text color to color \p n.
+    Sets the default text color for the lines in the browser to color \p col.
   */
-  void textcolor(unsigned n) {textcolor_ = n;}
+  void textcolor(unsigned col) { textcolor_ = col; }
 
   /**
-    Gets the width of any scrollbars that are used.
+    Gets the current width of scrollbars in pixels.
   */
-  static int scrollbar_width() {return scrollbar_width_;}
+  static int scrollbar_width() { return scrollbar_width_; }
   /**
-    Sets the width of any scrollbars that are used to \p b.
+    Sets the width of scrollbars to pixel size \p width.
   */
-  static void scrollbar_width(int b) {scrollbar_width_ = b;}
+  static void scrollbar_width(int width) { scrollbar_width_ = width; }
 
   /**
     Moves the vertical scrollbar to the righthand side of the list.
     For back compatibility.
   */
-  void scrollbar_right() {scrollbar.align(FL_ALIGN_RIGHT);}
+  void scrollbar_right() { scrollbar.align(FL_ALIGN_RIGHT); }
   /**
     Moves the vertical scrollbar to the lefthand side of the list.
     For back compatibility.
   */
-  void scrollbar_left() {scrollbar.align(FL_ALIGN_LEFT);}
-
-  /**
-   Sort the items in the browser.
-   item_swap(void*, void*) and item_text(void*) must be implemented for this call.
-   \param[in] flags no flags were defined yet. Sorting in descending order and 
-                    sorting while ignoring case come to mind.
-   */
+  void scrollbar_left() { scrollbar.align(FL_ALIGN_LEFT); }
   void sort(int flags=0);
-
 };
 
 #endif
diff --git a/src/Fl_Browser.cxx b/src/Fl_Browser.cxx
index add2e3171..d6934435b 100644
--- a/src/Fl_Browser.cxx
+++ b/src/Fl_Browser.cxx
@@ -460,7 +460,7 @@ int Fl_Browser::full_height() const {
 }
 
 /**
-  The default height of items (including spacing in-between) in pixels.
+  The default 'average' item height (including inter-item spacing) in pixels.
   This currently returns textsize() + 2.
   \returns The value in pixels.
 */
@@ -629,10 +629,10 @@ void Fl_Browser::clear() {
 /**
   Adds a new line to the end of the browser.
 
-  The text string newtext may contain format characters; see format_char() for details.
+  The text string \p newtext may contain format characters; see format_char() for details.
   \p newtext is copied using the strdup() function, and can be NULL to make a blank line.
 
-  The optional void * argument \p d will be the data() for the new item.
+  The optional void* argument \p d will be the data() for the new item.
 
   \param[in] newtext The label text used for the added item
   \param[in] d Optional user data() for the item (0 if unspecified)
@@ -753,7 +753,7 @@ int Fl_Browser::value() const {
 
 /**
   Swap the two items \p a and \p b.
-  You must call redraw() to make any changes visible.
+  Uses swapping() to ensure list updates correctly.
   \param[in] a,b The two items to be swapped.
 */
 void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx
index edf972f7d..1a150335c 100644
--- a/src/Fl_Browser_.cxx
+++ b/src/Fl_Browser_.cxx
@@ -36,7 +36,7 @@
 
 // This is the base class for browsers.  To be useful it must be
 // subclassed and several virtual functions defined.  The
-// Forms-compatable browser and the file chooser's browser are
+// Forms-compatible browser and the file chooser's browser are
 // subclassed off of this.
 
 // Yes, I know this should be a template...
@@ -72,22 +72,26 @@ static void hscrollbar_callback(Fl_Widget* s, void*) {
 int Fl_Browser_::scrollbar_width_ = 16;
 
 /**
-    Gets the default scrollbar size that is used by the
-    Fl_Browser_,
-    Fl_Help_View,
-    Fl_Scroll, and
-    Fl_Text_Display widgets.
+  Gets the default scrollbar size used by 
+  Fl_Browser_,
+  Fl_Help_View,
+  Fl_Scroll, and
+  Fl_Text_Display widgets.
+  \returns The default size for widget scrollbars, in pixels.
+  \todo The source code for this method needs to be moved from Fl_Browser_.cxx to Fl.cxx
 */
 int Fl::scrollbar_size() {
   return Fl_Browser_::scrollbar_width();
 }
 
 /**
-    Sets the default scrollbar size that is used by the
-    Fl_Browser_,
-    Fl_Help_View,
-    Fl_Scroll, and
-    Fl_Text_Display widgets.
+  Sets the default scrollbar size that is used by the
+  Fl_Browser_,
+  Fl_Help_View,
+  Fl_Scroll, and
+  Fl_Text_Display widgets.
+  \param[in] W The new default size for widget scrollbars, in pixels.
+  \todo The source code for this method needs to be moved from Fl_Browser_.cxx to Fl.cxx
 */
 void Fl::scrollbar_size(int W) {
   Fl_Browser_::scrollbar_width(W);
@@ -95,8 +99,10 @@ void Fl::scrollbar_size(int W) {
 
 // return where to draw the actual box:
 /**
-  This method returns the bounding box for the interior of the list, inside
+  Returns the bounding box for the interior of the list's display window, inside
   the scrollbars.
+  \param[out] X,Y,W,H The returned bounding box.\n
+                      (The original contents of these parameters are overwritten)
 */
 void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
   Fl_Boxtype b = box() ? box() : FL_DOWN_BOX;
@@ -119,6 +125,8 @@ void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
 /**
   This method returns the X position of the left edge of the list area
   after adjusting for the scrollbar and border, if any.
+  \returns The X position of the left edge of the list, in pixels.
+  \see Fl_Browser_::bbox()
 */
 int Fl_Browser_::leftedge() const {
   int X, Y, W, H; bbox(X, Y, W, H);
@@ -128,7 +136,10 @@ int Fl_Browser_::leftedge() const {
 // The scrollbars may be moved again by draw(), since each one's size
 // depends on whether the other is visible or not.  This skips over
 // Fl_Group::resize since it moves the scrollbars uselessly.
-/**  Repositions and/or resizes the browser.*/
+/**
+  Repositions and/or resizes the browser.
+  \param[in] X,Y,W,H The new position and size for the browser, in pixels.
+*/
 void Fl_Browser_::resize(int X, int Y, int W, int H) {
   Fl_Widget::resize(X, Y, W, H);
   // move the scrollbars so they can respond to events:
@@ -143,12 +154,14 @@ void Fl_Browser_::resize(int X, int Y, int W, int H) {
 
 // Cause minimal update to redraw the given item:
 /**
-  This method should be called when the contents of an item have changed
-  but not changed the height of the item.
+  This method should be called when the contents of \p item has changed,
+  but not its height.
+  \param[in] item The item that needs to be redrawn.
+  \see Related methods: redraw_lines(), redraw_line()
 */
-void Fl_Browser_::redraw_line(void* l) {
-  if (!redraw1 || redraw1 == l) {redraw1 = l; damage(FL_DAMAGE_EXPOSE);}
-  else if (!redraw2 || redraw2 == l) {redraw2 = l; damage(FL_DAMAGE_EXPOSE);}
+void Fl_Browser_::redraw_line(void* item) {
+  if (!redraw1 || redraw1 == item) {redraw1 = item; damage(FL_DAMAGE_EXPOSE);}
+  else if (!redraw2 || redraw2 == item) {redraw2 = item; damage(FL_DAMAGE_EXPOSE);}
   else damage(FL_DAMAGE_SCROLL);
 }
 
@@ -209,39 +222,49 @@ void Fl_Browser_::update_top() {
 // Change position(), top() will update when update_top() is called
 // (probably by draw() or handle()):
 /**
-  Gets or sets the vertical scrolling position of the list,
-  which is the pixel offset of the list items within the list
-  area.
+  Sets the vertical scroll position of the list to pixel position \p pos.
+  The position is how many pixels of the list are scrolled off the top edge
+  of the screen. Example: A position of '3' scrolls the top three pixels of
+  the list off the top edge of the screen.
+  \param[in] pos The vertical position (in pixels) to scroll the browser to.
+  \see Related methods: position(), hposition()
 */
-void Fl_Browser_::position(int yy) {
-  if (yy < 0) yy = 0;
-  if (yy == position_) return;
-  position_ = yy;
-  if (yy != real_position_) redraw_lines();
+void Fl_Browser_::position(int pos) {
+  if (pos < 0) pos = 0;
+  if (pos == position_) return;
+  position_ = pos;
+  if (pos != real_position_) redraw_lines();
 }
 
 /**
-  Gets or sets the horizontal scrolling position of the list,
-  which is the pixel offset of the list items within the list
-  area.
+  Sets the horizontal scroll position of the list to pixel position \p pos.
+  The position is how many pixels of the list are scrolled off the left edge
+  of the screen. Example: A position of '18' scrolls the left 18 pixels of the list
+  off the left edge of the screen.
+  \param[in] pos The horizontal position (in pixels) to scroll the browser to.
+  \see Related methods: position(), hposition()
 */
-void Fl_Browser_::hposition(int xx) {
-  if (xx < 0) xx = 0;
-  if (xx == hposition_) return;
-  hposition_ = xx;
-  if (xx != real_hposition_) redraw_lines();
+void Fl_Browser_::hposition(int pos) {
+  if (pos < 0) pos = 0;
+  if (pos == hposition_) return;
+  hposition_ = pos;
+  if (pos != real_hposition_) redraw_lines();
 }
 
 // Tell whether item is currently displayed:
 /**
-  This method returns non-zero if item p is currently visible in
-  the list.
+  Returns non-zero if \p item has been scrolled to a position where it is being displayed.
+  Checks to see if the item's vertical position is within the top and bottom
+  edges of the display window. This does NOT take into account the hide()/show()
+  status of the widget or item.
+  \param[in] item The item to check
+  \returns 1 if visible, 0 if not visible.
 */
-int Fl_Browser_::displayed(void* p) const {
+int Fl_Browser_::displayed(void* item) const {
   int X, Y, W, H; bbox(X, Y, W, H);
   int yy = H+offset_;
   for (void* l = top_; l && yy > 0; l = item_next(l)) {
-    if (l == p) return 1;
+    if (l == item) return 1;
     yy -= item_height(l);
   }
   return 0;
@@ -249,12 +272,15 @@ int Fl_Browser_::displayed(void* p) const {
 
 // Ensure this item is displayed:
 // Messy because we have no idea if it is before top or after bottom:
-/**  Displays item p, scrolling the list as necessary.*/
-void Fl_Browser_::display(void* p) {
+/**
+  Displays the \p item, scrolling the list as necessary.
+  \param[in] item The item to be displayed.
+*/
+void Fl_Browser_::display(void* item) {
 
   // First special case - want to display first item in the list?
   update_top();
-  if (p == item_first()) {position(0); return;}
+  if (item == item_first()) {position(0); return;}
 
   int X, Y, W, H, Yp; bbox(X, Y, W, H);
   void* l = top_;
@@ -262,11 +288,11 @@ void Fl_Browser_::display(void* p) {
   int h1;
 
   // 2nd special case - want to display item already displayed at top of browser?
-  if (l == p) {position(real_position_+Y); return;} // scroll up a bit
+  if (l == item) {position(real_position_+Y); return;} // scroll up a bit
 
   // 3rd special case - want to display item just above top of browser?
   void* lp = item_prev(l);
-  if (lp == p) {position(real_position_+Y-item_quick_height(lp)); return;}
+  if (lp == item) {position(real_position_+Y-item_quick_height(lp)); return;}
 
 #ifdef DISPLAY_SEARCH_BOTH_WAYS_AT_ONCE
   // search for item.  We search both up and down the list at the same time,
@@ -275,7 +301,7 @@ void Fl_Browser_::display(void* p) {
   while (l || lp) {
     if (l) {
       h1 = item_quick_height(l);
-      if (l == p) {
+      if (l == item) {
 	if (Y <= H) { // it is visible or right at bottom
 	  Y = Y+h1-H; // find where bottom edge is
 	  if (Y > 0) position(real_position_+Y); // scroll down a bit
@@ -290,7 +316,7 @@ void Fl_Browser_::display(void* p) {
     if (lp) {
       h1 = item_quick_height(lp);
       Yp -= h1;
-      if (lp == p) {
+      if (lp == item) {
 	if ((Yp + h1) >= 0) position(real_position_+Yp);
 	else position(real_position_+Yp-(H-h1)/2);
 	return;
@@ -304,7 +330,7 @@ void Fl_Browser_::display(void* p) {
   l = top_;
   for (; l; l = item_next(l)) {
     h1 = item_quick_height(l);
-    if (l == p) {
+    if (l == item) {
       if (Y <= H) { // it is visible or right at bottom
 	Y = Y+h1-H; // find where bottom edge is
 	if (Y > 0) position(real_position_+Y); // scroll down a bit
@@ -321,7 +347,7 @@ void Fl_Browser_::display(void* p) {
   for (; l; l = item_prev(l)) {
     h1 = item_quick_height(l);
     Y -= h1;
-    if (l == p) {
+    if (l == item) {
       if ((Y + h1) >= 0) position(real_position_+Y);
       else position(real_position_+Y-(H-h1)/2);
       return;
@@ -331,7 +357,6 @@ void Fl_Browser_::display(void* p) {
 }
 
 // redraw, has side effect of updating top and setting scrollbar:
-
 /**
   Draws the list within the normal widget bounding box.
 */
@@ -490,6 +515,8 @@ J1:
   This method should be called when the list data is completely replaced
   or cleared. It informs the Fl_Browser_ widget that any cached
   information it has concerning the items is invalid.
+  This method does not clear the list, it just handles the follow up
+  bookkeeping after the list has been cleared.
 */
 void Fl_Browser_::new_list() {
   top_ = 0;
@@ -505,18 +532,20 @@ void Fl_Browser_::new_list() {
 // Tell it that this item is going away, and that this must remove
 // all pointers to it:
 /**
-  This method should be used when an item is deleted from the list.
-  It allows the Fl_Browser_ to discard any cached data it has
-  on the item.
+  This method should be used when \p item is being deleted from the list.
+  It allows the Fl_Browser_ to discard any cached data it has on the item.
+  This method does not actually delete the item, but handles the follow up
+  bookkeeping after the item has just been deleted.
+  \param[in] item The item being deleted.
 */
-void Fl_Browser_::deleting(void* l) {
-  if (displayed(l)) {
+void Fl_Browser_::deleting(void* item) {
+  if (displayed(item)) {
     redraw_lines();
-    if (l == top_) {
+    if (item == top_) {
       real_position_ -= offset_;
       offset_ = 0;
-      top_ = item_next(l);
-      if (!top_) top_ = item_prev(l);
+      top_ = item_next(item);
+      if (!top_) top_ = item_prev(item);
     }
   } else {
     // we don't know where this item is, recalculate top...
@@ -524,13 +553,18 @@ void Fl_Browser_::deleting(void* l) {
     offset_ = 0;
     top_ = 0;
   }
-  if (l == selection_) selection_ = 0;
-  if (l == max_width_item) {max_width_item = 0; max_width = 0;}
+  if (item == selection_) selection_ = 0;
+  if (item == max_width_item) {max_width_item = 0; max_width = 0;}
 }
 
 /**
-  This method should be used when an item is replaced in the list.
-  It allows the Fl_Browser_ to update its cache data as needed.
+  This method should be used when item \p a is being replaced by item \p b.
+  It allows the Fl_Browser_ to update its cache data as needed,
+  schedules a redraw for the item being changed, and tries to maintain the selection.
+  This method does not actually replace the item, but handles the follow up
+  bookkeeping after the item has just been replaced.
+  \param[in] a Item being replaced
+  \param[in] b Item to replace 'a'
 */
 void Fl_Browser_::replacing(void* a, void* b) {
   redraw_line(a);
@@ -540,7 +574,12 @@ void Fl_Browser_::replacing(void* a, void* b) {
 }
 
 /**
-  Exchange pointers \p a and \p b.
+  This method should be used when two items \p a and \p b are being swapped.
+  It allows the Fl_Browser_ to update its cache data as needed,
+  schedules a redraw for the two items, and tries to maintain the current selection.
+  This method does not actually swap items, but handles the follow up
+  bookkeeping after items have been swapped.
+  \param[in] a,b Items being swapped.
 */
 void Fl_Browser_::swapping(void* a, void* b) {
   redraw_line(a);
@@ -552,8 +591,14 @@ void Fl_Browser_::swapping(void* a, void* b) {
 }
 
 /**
-  This method should be used when an item is added to the list.
-  It allows the Fl_Browser_ to update its cache data as needed.
+  This method should be used when an item is in the process of
+  being inserted into the list.
+  It allows the Fl_Browser_ to update its cache data as needed,
+  scheduling a redraw for the affected lines.
+  This method does not actually insert items, but handles the 
+  follow up bookkeeping after items have been inserted.
+  \param[in] a The starting item position
+  \param[in] b The new item being inserted
 */
 void Fl_Browser_::inserting(void* a, void* b) {
   if (displayed(a)) redraw_lines();
@@ -561,52 +606,59 @@ void Fl_Browser_::inserting(void* a, void* b) {
 }
 
 /**
-  This method returns the item under mouse at my. If no item is
-  displayed at that position then NULL is returned.
+  This method returns the item under mouse y position \p ypos.
+  NULL is returned if no item is displayed at that position.
+  \param[in] ypos The y position (eg. Fl::event_y()) to find an item under.
+  \returns The item, or NULL if not found
 */
-void* Fl_Browser_::find_item(int my) {
+void* Fl_Browser_::find_item(int ypos) {
   update_top();
   int X, Y, W, H; bbox(X, Y, W, H);
-  void* l;
   int yy = Y-offset_;
-  for (l = top_; l; l = item_next(l)) {
+  for (void *l = top_; l; l = item_next(l)) {
     int hh = item_height(l); if (hh <= 0) continue;
     yy += hh;
-    if (my <= yy || yy>=(Y+H)) return l;
+    if (ypos <= yy || yy>=(Y+H)) return l;
   }
   return 0;
 }
 
 /**
-  Sets the selection state of item p to s and
-  returns 1 if the state changed or 0 if it did not.
+  Sets the selection state of \p item to \p val,
+  and returns 1 if the state changed or 0 if it did not.
   
-  <P>If docb is non-zero, select tries to call the callback
-  function for the widget.
+  If \p docallbacks is non-zero, select tries to call
+  the callback function for the widget.
+
+  \param[in] item The item whose selection state is to be changed
+  \param[in] val The new selection state (1=select, 0=de-select)
+  \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+                         If 0, doesn't do callback (default).
+  \returns 1 if state was changed, 0 if not.
 */
-int Fl_Browser_::select(void* l, int i, int docallbacks) {
+int Fl_Browser_::select(void* item, int val, int docallbacks) {
   if (type() == FL_MULTI_BROWSER) {
-    if (selection_ != l) {
+    if (selection_ != item) {
       if (selection_) redraw_line(selection_);
-      selection_ = l;
-      redraw_line(l);
+      selection_ = item;
+      redraw_line(item);
     }
-    if ((!i)==(!item_selected(l))) return 0;
-    item_select(l, i);
-    redraw_line(l);
+    if ((!val)==(!item_selected(item))) return 0;
+    item_select(item, val);
+    redraw_line(item);
   } else {
-    if (i && selection_ == l) return 0;
-    if (!i && selection_ != l) return 0;
+    if (val && selection_ == item) return 0;
+    if (!val && selection_ != item) return 0;
     if (selection_) {
       item_select(selection_, 0);
       redraw_line(selection_);
       selection_ = 0;
     }
-    if (i) {
-      item_select(l, 1);
-      selection_ = l;
-      redraw_line(l);
-      display(l);
+    if (val) {
+      item_select(item, 1);
+      selection_ = item;
+      redraw_line(item);
+      display(item);
     }
   }	    
   if (docallbacks) {
@@ -620,8 +672,11 @@ int Fl_Browser_::select(void* l, int i, int docallbacks) {
   Deselects all items in the list and returns 1 if the state changed
   or 0 if it did not.
   
-  <P>If docb is non-zero, deselect tries to call the
-  callback function for the widget.
+  If the optional \p docallbacks parameter is non-zero, deselect tries
+  to call the callback function for the widget.
+
+  \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+                         If 0, doesn't do callback (default).
 */
 int Fl_Browser_::deselect(int docallbacks) {
   if (type() == FL_MULTI_BROWSER) {
@@ -639,24 +694,29 @@ int Fl_Browser_::deselect(int docallbacks) {
 }
 
 /**
-  Selects item p and returns 1 if the state changed or 0 if it did
-  not. Any other items in the list are deselected.
-  
-  <P>If docb is non-zero, select_only tries to call the
-  callback function for the widget.
+  Selects \p item and returns 1 if the state changed or 0 if it did not.
+  Any other items in the list are deselected.
+  \param[in] item The \p item to select.
+  \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+                         If 0, doesn't do callback (default).
 */
-int Fl_Browser_::select_only(void* l, int docallbacks) {
-  if (!l) return deselect(docallbacks);
+int Fl_Browser_::select_only(void* item, int docallbacks) {
+  if (!item) return deselect(docallbacks);
   int change = 0;
   if (type() == FL_MULTI_BROWSER) {
     for (void* p = item_first(); p; p = item_next(p))
-      if (p != l) change |= select(p, 0, docallbacks);
+      if (p != item) change |= select(p, 0, docallbacks);
   }
-  change |= select(l, 1, docallbacks);
-  display(l);
+  change |= select(item, 1, docallbacks);
+  display(item);
   return change;
 }
-/** Handles an event within the normal widget bounding box. */
+
+/**
+  Handles the \p event within the normal widget bounding box.
+  \param[in] event The event to process.
+  \returns 1 if event was processed, 0 if not.
+*/
 int Fl_Browser_::handle(int event) {
   // must do shortcuts first or the scrollbar will get them...
   if (event == FL_ENTER || event == FL_LEAVE) return 1;
@@ -873,9 +933,13 @@ J1:
   return 0;
 }
 
-/** The constructor makes an empty browser.*/
-Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
-  : Fl_Group(X, Y, W, H, l),
+/**
+  The constructor makes an empty browser.
+  \param[in] X,Y,W,H position and size.
+  \param[in] L The label string, may be NULL.
+*/
+Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* L)
+  : Fl_Group(X, Y, W, H, L),
     scrollbar(0, 0, 0, 0, 0), // they will be resized by draw()
     hscrollbar(0, 0, 0, 0, 0)
 {
@@ -902,11 +966,20 @@ Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
   end();
 }
 
-/*
- * Simple bubble sort - pure lazyness on my side.
- */
+/**
+  Sort the items in the browser based on \p flags.
+  item_swap(void*, void*) and item_text(void*) must be implemented for this call.
+  \param[in] flags FL_SORT_ASCENDING -- sort in ascending order\n
+                   FL_SORT_DESCENDING -- sort in descending order\n
+		   Values other than the above will cause undefined behavior\n
+		   Other flags may appear in the future.
+  \todo Add a flag to ignore case
+*/
 void Fl_Browser_::sort(int flags) {
-  int i, j, n = -1, desc = ((flags&FL_SORT_DESC)==FL_SORT_DESC);
+  //
+  // Simple bubble sort - pure lazyness on my side.
+  //
+  int i, j, n = -1, desc = ((flags&FL_SORT_DESCENDING)==FL_SORT_DESCENDING);
   void *a =item_first(), *b, *c;
   if (!a) return;
   while (a) {
@@ -943,20 +1016,23 @@ void Fl_Browser_::sort(int flags) {
 
 /**
   This method may be provided by the subclass to return the height of the
-  item p in pixels.  Allow for two additional pixels for the list
-  selection box.  This method differs from
-  item_height in that it is only
-  called for selection and scrolling operations. The default implementation
-  calls item_height.
+  \p item, in pixels.  
+  Allow for two additional pixels for the list selection box.
+  This method differs from item_height in that it is only called for 
+  selection and scrolling operations. 
+  The default implementation calls item_height.
+  \param[in] item The item whose height to return.
+  \returns The height, in pixels.
 */
-int Fl_Browser_::item_quick_height(void* l) const {
-  return item_height(l);
+int Fl_Browser_::item_quick_height(void* item) const {
+  return item_height(item);
 }
 
 /**
-  This method may be provided to return the average height of all items, to
-  be used for scrolling. The default implementation uses the height of the first
-  item.
+  This method may be provided to return the average height of all items
+  to be used for scrolling. 
+  The default implementation uses the height of the first item.
+  \returns The average height of items, in pixels.
 */
 int Fl_Browser_::incr_height() const {
   return item_quick_height(item_first());
@@ -964,8 +1040,10 @@ int Fl_Browser_::incr_height() const {
 
 /**
   This method may be provided by the subclass to indicate the full height
-  of the item list in pixels. The default implementation computes the full
-  height from the item heights.
+  of the item list, in pixels. 
+  The default implementation computes the full height from the item heights. 
+  Includes the items that are scrolled off screen.
+  \returns The height of the entire list, in pixels.
 */
 int Fl_Browser_::full_height() const {
   int t = 0;
@@ -976,26 +1054,32 @@ int Fl_Browser_::full_height() const {
 
 /**
   This method may be provided by the subclass to indicate the full width
-  of the item list in pixels. The default implementation computes the full
-  width from the item widths.
+  of the item list, in pixels. 
+  The default implementation computes the full width from the item widths.
+  \returns The maximum width of all the items, in pixels.
 */
 int Fl_Browser_::full_width() const {
   return max_width;
 }
 
 /**
-  This method must be implemented by the subclass if it supports
-  multiple selections in the browser. The s argument specifies the
-  selection state for item p: 0 = off, 1 = on.
+  This method must be implemented by the subclass if it supports 
+  multiple selections; sets the selection state to \p val for the \p item.
+  Sets the selection state for \p item, where optional \p val is 1 (select, the default)
+  or 0 (de-select).
+  \param[in] item The item to be selected
+  \param[in] val The optional selection state; 1=select, 0=de-select.\n
+                 The default is to select the item (1).
 */
-void Fl_Browser_::item_select(void*, int) {}
+void Fl_Browser_::item_select(void *item, int val) {}
 
 /**
   This method must be implemented by the subclass if it supports
-  multiple selections in the browser. The method should return 1 if p
-  is selected and 0 otherwise.
+  multiple selections; returns the selection state for \p item.
+  The method should return 1 if \p item is selected, or 0 otherwise.
+  \param[in] item The item to test.
 */
-int Fl_Browser_::item_selected(void* l) const {return l==selection_;}
+int Fl_Browser_::item_selected(void* item) const { return item==selection_ ? 1 : 0; }
 
 //
 // End of "$Id$".
diff --git a/test/browser.cxx b/test/browser.cxx
index fe78dbc4b..77da66cde 100644
--- a/test/browser.cxx
+++ b/test/browser.cxx
@@ -119,7 +119,7 @@ void swap_cb(Fl_Widget *, void *) {
 }
 
 void sort_cb(Fl_Widget *, void *) {
-  browser->sort(FL_SORT_ASC);
+  browser->sort(FL_SORT_ASCENDING);
 }
 
 int main(int argc, char **argv) {