Documenting the public methods Fl_Tabs::push()

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

2 files changed, 17 insertions, 2 deletions

diff --git a/FL/Fl_Tabs.H b/FL/Fl_Tabs.H
index 009e07be3..15fe27674 100644
--- a/FL/Fl_Tabs.H
+++ b/FL/Fl_Tabs.H
@@ -69,7 +69,14 @@ public:
   Fl_Widget *value();
   int value(Fl_Widget *);
   /**
-  \todo This public method needs to be documented
+    Returns the tab group for the tab the user has currently down-clicked on
+    and remains over until FL_RELEASE. Otherwise, returns NULL.
+
+    While the user is down-clicked on a tab, the return value is the tab group
+    for that tab. But as soon as the user releases, or drags off the tab with
+    the button still down, the return value will be NULL.
+
+    \see push(Fl_Widget*).
   */
   Fl_Widget *push() const {return push_;}
   int push(Fl_Widget *);
diff --git a/src/Fl_Tabs.cxx b/src/Fl_Tabs.cxx
index 430d9cf4b..67d41c40a 100644
--- a/src/Fl_Tabs.cxx
+++ b/src/Fl_Tabs.cxx
@@ -263,7 +263,15 @@ int Fl_Tabs::handle(int event) {
 }
 
 /**
-  \todo This public method needs to be documented
+  This is called by the tab widget's handle() method to set the
+  tab group widget the user last FL_PUSH'ed on. Set back to zero
+  on FL_RELEASE.
+
+  As of this writing, the value is mainly used by draw_tab()
+  to determine whether or not to draw a 'down' box for the tab
+  when it's clicked, and to turn it off if the user drags off it.
+
+  \see push().
 */
 int Fl_Tabs::push(Fl_Widget *o) {
   if (push_ == o) return 0;