More Fl_Tree doc improvements.

Only docs changed here, no code changed..
one method's definition moved to match similar method organization.

Some redundant docs (for const vs. non-const) changed
by referring the non-const method to the const one, to reduce size.



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

2 files changed, 37 insertions, 50 deletions

diff --git a/src/Fl_Tree.cxx b/src/Fl_Tree.cxx
index b5351aadd..711c9f217 100644
--- a/src/Fl_Tree.cxx
+++ b/src/Fl_Tree.cxx
@@ -568,6 +568,7 @@ static void redraw_soon(void *data) {
 /// This method is called when the widget is resize()ed or if the
 /// scrollbar's sizes are changed (affects tree widget's inner dimensions
 /// tix/y/w/h), and also used by calc_tree().
+/// \version 1.3.3 ABI feature
 ///
 void Fl_Tree::calc_dimensions() {
   // Calc tree outer xywh
@@ -751,6 +752,7 @@ void Fl_Tree::draw() {
   }
 }
 #else
+/// Standard FLTK draw() method, handles drawing the tree widget.
 void Fl_Tree::draw() {
   int ytoofar = draw_tree();
 
@@ -1051,16 +1053,8 @@ void Fl_Tree::clear_children(Fl_Tree_Item *item) {
 ///
 /// \param[in] path -- the tree item's pathname to be found (e.g. "Flintstones/Fred")
 /// \returns The item, or NULL if not found.
-///
 /// \see item_pathname()
 ///
-Fl_Tree_Item *Fl_Tree::find_item(const char *path) {
-  // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
-  return(const_cast<Fl_Tree_Item*>(
-	 static_cast<const Fl_Tree&>(*this).find_item(path)));
-}
-
-/// A const version of Fl_Tree::find_item(const char *path)
 const Fl_Tree_Item *Fl_Tree::find_item(const char *path) const {
   if ( ! _root ) return(NULL);
   char **arr = parse_path(path);
@@ -1069,6 +1063,13 @@ const Fl_Tree_Item *Fl_Tree::find_item(const char *path) const {
   return(item);
 }
 
+/// Non-const version of Fl_Tree::find_item(const char *path) const
+Fl_Tree_Item *Fl_Tree::find_item(const char *path) {
+  // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
+  return(const_cast<Fl_Tree_Item*>(
+	 static_cast<const Fl_Tree&>(*this).find_item(path)));
+}
+
 // Handle safe 'reverse string concatenation'.
 //   In the following we build the pathname from right-to-left,
 //   since we start at the child and work our way up to the root.
@@ -1138,13 +1139,15 @@ int Fl_Tree::item_pathname(char *pathname, int pathnamelen, const Fl_Tree_Item *
 /// \param[in] yonly -- 0: check both event's X and Y values.
 ///                  -- 1: only check event's Y value, don't care about X.
 /// \returns The item clicked, or NULL if no item was under the current event.
-/// \version 1.3.0, added yonly parameter as a 1.3.3 ABI feature.
+/// \version 1.3.0
+/// \version 1.3.3 ABI feature: added yonly parameter
 ///
 const Fl_Tree_Item* Fl_Tree::find_clicked(int yonly) const {
   if ( ! _root ) return(NULL);
   return(_root->find_clicked(_prefs, yonly));
 }
 
+/// Non-const version of Fl_Tree::find_clicked(int yonly) const.
 Fl_Tree_Item *Fl_Tree::find_clicked(int yonly) {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(
@@ -1168,6 +1171,9 @@ const Fl_Tree_Item* Fl_Tree::find_clicked() const {
   if ( ! _root ) return(NULL);
   return(_root->find_clicked(_prefs));
 }
+
+/// Non-const version of Fl_Tree::find_clicked() const.
+/// \version 1.3.0
 Fl_Tree_Item *Fl_Tree::find_clicked() {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(
@@ -2423,38 +2429,45 @@ void Fl_Tree::selectmode(Fl_Tree_Select val) {
 }
 
 #if FLTK_ABI_VERSION >= 10301
-/// Returns the current item re/selection mode
+/// Returns the current item re/selection mode.
+/// \version 1.3.1 ABI feature
+///
 Fl_Tree_Item_Reselect_Mode Fl_Tree::item_reselect_mode() const {
   return(_prefs.item_reselect_mode());
 }
 
 /// Sets the item re/selection mode
 /// See ::Fl_Tree_Item_Reselect_Mode for possible values.
+/// \version 1.3.1 ABI feature
 ///
 void Fl_Tree::item_reselect_mode(Fl_Tree_Item_Reselect_Mode mode) {
   _prefs.item_reselect_mode(mode);
 }
-#endif
 
-#if FLTK_ABI_VERSION >= 10301
 /// Get the 'item draw mode' used for the tree
+/// \version 1.3.1 ABI feature
+///
 Fl_Tree_Item_Draw_Mode Fl_Tree::item_draw_mode() const {
   return(_prefs.item_draw_mode());
 }
 
 /// Set the 'item draw mode' used for the tree to \p 'mode'.
-///     This affects how items in the tree are drawn,
-///     such as when a widget() is defined. 
-///     See ::Fl_Tree_Item_Draw_Mode for possible values.
+///
+/// This affects how items in the tree are drawn,
+/// such as when a widget() is defined. 
+/// See ::Fl_Tree_Item_Draw_Mode for possible values.
+/// \version 1.3.1 ABI feature
 ///
 void Fl_Tree::item_draw_mode(Fl_Tree_Item_Draw_Mode mode) {
   _prefs.item_draw_mode(mode);
 }
 
 /// Set the 'item draw mode' used for the tree to integer \p 'mode'.
-///     This affects how items in the tree are drawn,
-///     such as when a widget() is defined. 
-///     See ::Fl_Tree_Item_Draw_Mode for possible values.
+///
+/// This affects how items in the tree are drawn,
+/// such as when a widget() is defined. 
+/// See ::Fl_Tree_Item_Draw_Mode for possible values.
+/// \version 1.3.1 ABI feature
 ///
 void Fl_Tree::item_draw_mode(int mode) {
   _prefs.item_draw_mode(Fl_Tree_Item_Draw_Mode(mode));
diff --git a/src/Fl_Tree_Item.cxx b/src/Fl_Tree_Item.cxx
index 202ad09a4..74c68438b 100644
--- a/src/Fl_Tree_Item.cxx
+++ b/src/Fl_Tree_Item.cxx
@@ -235,12 +235,7 @@ const Fl_Tree_Item* Fl_Tree_Item::find_child_item(const char *name) const {
   return(0);
 }
 
-/// Return the /immediate/ child of current item
-/// that has the label \p 'name'.
-///
-/// \returns found item, or 0 if not found.
-/// \version 1.3.3
-///
+/// Non-const version of Fl_Tree_Item::find_child_item(const char *name) const.
 Fl_Tree_Item* Fl_Tree_Item::find_child_item(const char *name) {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(
@@ -269,13 +264,7 @@ const Fl_Tree_Item *Fl_Tree_Item::find_child_item(char **arr) const {
   return(0);
 }
 
-/// Find child item by descending array \p 'arr' of names.
-/// Does not include self in search.
-/// Only Fl_Tree should need this method. Use Fl_Tree::find_item() instead.
-///
-/// \returns item, or 0 if not found
-/// \version 1.3.0 release
-///
+/// Non-const version of Fl_Tree_Item::find_child_item(char **arr) const.
 Fl_Tree_Item *Fl_Tree_Item::find_child_item(char **arr) {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(
@@ -300,12 +289,7 @@ const Fl_Tree_Item *Fl_Tree_Item::find_item(char **names) const {
   return(0);
 }
 
-/// Find item by descending array of \p 'names'.
-/// Includes self in search.
-/// Only Fl_Tree should need this method.
-///
-/// \returns item, or 0 if not found
-///
+/// Non-const version of Fl_Tree_Item::find_item(char **names) const.
 Fl_Tree_Item *Fl_Tree_Item::find_item(char **names) {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(
@@ -656,6 +640,7 @@ void Fl_Tree_Item::draw_vertical_connector(int x, int y1, int y2, const Fl_Tree_
 /// \param[in] yonly -- 0: check both event's X and Y values.
 ///                  -- 1: only check event's Y value, don't care about X.
 /// \returns pointer to clicked item, or NULL if none found
+/// \version 1.3.3 ABI feature
 ///
 const Fl_Tree_Item *Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs &prefs, int yonly) const {
   if ( ! is_visible() ) return(0);
@@ -684,14 +669,7 @@ const Fl_Tree_Item *Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs &prefs, int y
   return(0);
 }
 
-/// Find the item that the last event was over.
-/// If \p 'yonly' is 1, only check event's y value, don't care about x.
-/// \param[in] prefs The parent tree's Fl_Tree_Prefs
-/// \param[in] yonly -- 0: check both event's X and Y values.
-///                  -- 1: only check event's Y value, don't care about X.
-/// \returns pointer to clicked item, or NULL if none found
-/// \version 1.3.3 ABI feature
-///
+/// Non-const version of Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs&,int) const
 Fl_Tree_Item *Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs &prefs, int yonly) {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(
@@ -723,11 +701,7 @@ const Fl_Tree_Item *Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs &prefs) const
   return(0);
 }
 
-/// Find the item that the last event was over.
-/// \param[in] prefs The parent tree's Fl_Tree_Prefs
-/// \returns pointer to clicked item, or NULL if none found
-/// \version 1.3.0
-///
+/// Non-const version of Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs&) const.
 Fl_Tree_Item *Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs &prefs) {
   // "Effective C++, 3rd Ed", p.23. Sola fide, Amen.
   return(const_cast<Fl_Tree_Item*>(