added doxygen comments for undocumented features in Fl, Fl_Gl_Window

- I see Fabien was/is? busy with Fl.H, so I submit the few changes
  I've made and hope I haven't trodden on his toes too much :-)



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

FL/Fl.H

@@ -39,7 +39,7 @@
 #  include "fl_utf8.h"
 #  include "Enumerations.H"
 #  ifndef Fl_Object
-#    define Fl_Object Fl_Widget
+#    define Fl_Object Fl_Widget	/**< for back compatibility - use Fl_Widget! */
 #  endif
 
 #  ifdef check
@@ -51,11 +51,20 @@ class Fl_Widget;
 class Fl_Window;
 class Fl_Image;
 struct Fl_Label;
+
+/** signature of some label drawing functions passed as parameters */
 typedef void (Fl_Label_Draw_F)(const Fl_Label*, int,int,int,int, Fl_Align);
+
+/** signature of some label measurement functions passed as parameters */
 typedef void (Fl_Label_Measure_F)(const Fl_Label*, int&, int&);
+
+/** signature of some box drawing functions passed as parameters */
 typedef void (Fl_Box_Draw_F)(int,int,int,int, Fl_Color);
 
+/** signature of some timeout callback functions passed as parameters */
 typedef void (*Fl_Timeout_Handler)(void*);
+
+/** signature of some wakeup callback functions passed as parameters */
 typedef void (*Fl_Awake_Handler)(void*);
 
 /**
@@ -96,6 +105,13 @@ public: // should be private!
   */
   static void damage(int d) {damage_ = d;}
 
+  /**
+    The currently executing idle callback function: DO NOT USE THIS DIRECTLY!
+    
+    This is now used as part of a higher level system allowing multiple
+    idle callback functions to be called.
+    \see add_idle(), remove_idle()
+  */
   static void (*idle)();
 
 #ifndef FL_DOXYGEN
@@ -123,6 +139,10 @@ public:
   static int arg(int, char**, int&);
   static int args(int, char**, int&, int (*)(int,char**,int&) = 0);
   static void args(int, char**);
+  /**
+    Usage string displayed if Fl::args() detects an invalid argument.
+    This may be changed to point to customized text at run-time.
+  */
   static const char* const help;
 
   // things called by initialization:
@@ -247,9 +267,9 @@ public:
   /** Removes a file descriptor handler. */
   static void remove_fd(int); // platform dependent
 
-  static void add_idle(void (*cb)(void*), void* = 0);
+  static void add_idle(void (*cb)(void*), void* data = 0);
-  static int  has_idle(void (*cb)(void*), void* = 0);
+  static int  has_idle(void (*cb)(void*), void* data = 0);
-  static void remove_idle(void (*cb)(void*), void* = 0);
+  static void remove_idle(void (*cb)(void*), void* data = 0);
   /** If true then flush() will do something. */
   static int damage() {return damage_;}
   static void redraw();

FL/Fl_Gl_Window.H

@@ -34,6 +34,9 @@
 #include "Fl_Window.H"
 
 #ifndef GLContext
+/**
+  opaque pointer type to hide system specific implementation.
+*/
 typedef void* GLContext; // actually a GLXContext or HGLDC
 #endif
 

src/Fl_add_idle.cxx

@@ -50,21 +50,21 @@ static void call_idle() {
 }
 
 /**
-    Adds a callback function that is called every time by
+  Adds a callback function that is called every time by Fl::wait() and also
-    Fl::wait() and also makes it act as though the timeout is
+  makes it act as though the timeout is zero (this makes Fl::wait() return
-    zero (this makes Fl::wait() return immediately, so if it is
+  immediately, so if it is in a loop it is called repeatedly, and thus the
-    in a loop it is called repeatedly, and thus the idle fucntion is
+  idle fucntion is called repeatedly).  The idle function can be used to get
-    called repeatedly).  The idle function can be used to get background
+  background processing done.
-    processing done.
     
-    <P>You can have multiple idle callbacks. To remove an idle callback use Fl::remove_idle().
+  You can have multiple idle callbacks. To remove an idle callback use
+  Fl::remove_idle().
     
-    <P>Fl::wait() and Fl::check() call idle callbacks,
+  Fl::wait() and Fl::check() call idle callbacks, but Fl::ready() does not.
-    but Fl::ready() does not.
     
-    <P>The idle callback can call any FLTK functions, including
+  The idle callback can call any FLTK functions, including Fl::wait(),
-    Fl::wait(), Fl::check(), and Fl::ready().
+  Fl::check(), and Fl::ready().
-    FLTK will not recursively call the idle callback.
+
+  FLTK will not recursively call the idle callback.
 */
 void Fl::add_idle(void (*cb)(void*), void* data) {
   idle_cb* p = freelist;
@@ -83,7 +83,9 @@ void Fl::add_idle(void (*cb)(void*), void* data) {
   }
 }
 
-/** Returns true if the specified idle callback is currently installed. */
+/**
+  Returns true if the specified idle callback is currently installed.
+*/
 int Fl::has_idle(void (*cb)(void*), void* data) {
   idle_cb* p = first;
   if (!p) return 0;
@@ -93,7 +95,9 @@ int Fl::has_idle(void (*cb)(void*), void* data) {
   }
 }
 
-/** Removes the specified idle callback, if it is installed. */
+/**
+  Removes the specified idle callback, if it is installed.
+*/
 void Fl::remove_idle(void (*cb)(void*), void* data) {
   idle_cb* p = first;
   if (!p) return;