Doxygen documentation. Completed Fl class, added a todo related to recent Fl API to document. Matt?. More cosmetics have been done, replaced *all* <pre> </pre> tags by \code \endcode sequences.

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

18 files changed, 172 insertions, 176 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index cad4ab87a..7820efef1 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -115,7 +115,20 @@ public:
   // things called by initialization:
   static void display(const char*);
   static int visual(int);
-  static int gl_visual(int, int *alist=0);
+  /**
+    This does the same thing as
+    Fl::visual(int) but also
+    requires OpenGL drawing to work.  This <I>must</I> be done if
+    you want to draw in normal windows with OpenGL with  gl_start() and
+    gl_end().  It may be useful to call this so your X
+    windows use the same visual as an
+    Fl_Gl_Window, which on
+    some servers will reduce colormap flashing.
+    
+    <P>See Fl_Gl_Window
+    for a list of additional values for the argument.
+  */
+  static int gl_visual(int, int *alist=0); // platform dependent
   static void own_colormap();
   static void get_system_colors();
   static void foreground(uchar, uchar, uchar);
@@ -142,8 +155,54 @@ public:
   static int ready();
   static int run();
   static Fl_Widget* readqueue();
-  static void add_timeout(double t, Fl_Timeout_Handler,void* = 0);
-  static void repeat_timeout(double t, Fl_Timeout_Handler,void* = 0);
+  /**
+  Adds a one-shot timeout callback.  The function will be called by
+  Fl::wait() at <i>t</i> seconds after this function is called.
+  The optional void* argument is passed to the callback.
+  
+  <P>You can have multiple timeout callbacks. To remove an timeout
+  callback use Fl::remove_timeout().
+  
+  <p>If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to
+  reschedule the subsequent timeouts.</p>
+  
+  <p>The following code will print &quot;TICK&quot; each second on
+  stdout with a fair degree of accuracy:</p>
+  
+  \code
+     void callback(void*) {
+       puts("TICK");
+       Fl::repeat_timeout(1.0, callback);
+     }
+  
+     int main() {
+       Fl::add_timeout(1.0, callback);
+       return Fl::run();
+     }
+  \endcode
+  */
+  static void add_timeout(double t, Fl_Timeout_Handler,void* = 0); // platform dependent
+  /**
+  This method repeats a timeout callback from the expiration of the
+  previous timeout, allowing for more accurate timing. You may only call
+  this method inside a timeout callback.
+  
+  <p>The following code will print &quot;TICK&quot; each second on
+  stdout with a fair degree of accuracy:</p>
+  
+  \code
+     void callback(void*) {
+       puts("TICK");
+       Fl::repeat_timeout(1.0, callback);
+     }
+  
+     int main() {
+       Fl::add_timeout(1.0, callback);
+       return Fl::run();
+     }
+  \endcode
+  */
+  static void repeat_timeout(double t, Fl_Timeout_Handler,void* = 0); // platform dependent
   static int  has_timeout(Fl_Timeout_Handler, void* = 0);
   static void remove_timeout(Fl_Timeout_Handler, void* = 0);
   static void add_check(Fl_Timeout_Handler, void* = 0);
diff --git a/FL/Fl_Clock.H b/FL/Fl_Clock.H
index da98bdcf8..f1bc513e7 100644
--- a/FL/Fl_Clock.H
+++ b/FL/Fl_Clock.H
@@ -47,11 +47,11 @@
 /**
  * This widget can be used to display a program-supplied time.
  * The time shown on the clock is not updated. 
- * To display the current time, use <TT>Fl_Clock</A></TT> instead.
+ * To display the current time, use Fl_Clock</A> instead.
  *
- * \image html clock.gif 
+ * <table align=CENTER border=5 cellpadding=5 ><TR><TD> \image html clock.gif  </TD>
  *
- * \image html round_clock.gif
+ * <TD> \image html round_clock.gif </TD> </TR> </table>
  */
 class FL_EXPORT Fl_Clock_Output : public Fl_Widget {
   int hour_, minute_, second_;
@@ -63,9 +63,9 @@ protected:
 public:
   
   /**
-   * Creates a new <tt>Fl_Clock_Output</tt> widget.
-   * Create an <tt>Fl_Clock_Output</tt> widget using the given position, 
-   * size, and label string. The default boxtype is <tt>FL_NO_BOX</tt>.
+   * Creates a new Fl_Clock_Output widget.
+   * Create an Fl_Clock_Output widget using the given position, 
+   * size, and label string. The default boxtype is FL_NO_BOX.
    *
    * \param[in] x, y, w, h position and size of the widget
    * \param[in] label widget label, default is no label
@@ -120,12 +120,12 @@ public:
 
 /**
  * This widget provides a round analog clock display.
- * <tt>Fl_Clock</tt> is provided for Forms compatibility. 
- * It installs a 1-second timeout callback using <tt>Fl::add_timeout()</tt>.
+ * Fl_Clock is provided for Forms compatibility. 
+ * It installs a 1-second timeout callback using Fl::add_timeout().
  *
- * \image html clock.gif 
+ * <table align=CENTER border=5 cellpadding=5 ><TR><TD>\image html clock.gif </TD>
  * 
- * \image html round_clock.gif
+ * <TD> \image html round_clock.gif </TD></TR></table>
  */
 class FL_EXPORT Fl_Clock : public Fl_Clock_Output {
 public:
@@ -133,9 +133,9 @@ public:
   void update();
 
   /**
-   * Creates a new <tt>Fl_Clock</tt> widget.
-   * Create an <tt>Fl_Clock</tt> widget using the given position, 
-   * size, and label string. The default boxtype is <tt>FL_NO_BOX</tt>.
+   * Creates a new Fl_Clock widget.
+   * Create an Fl_Clock widget using the given position, 
+   * size, and label string. The default boxtype is FL_NO_BOX.
    *
    * \param[in] x, y, w, h position and size of the widget
    * \param[in] label widget label, default is no label
@@ -143,8 +143,8 @@ public:
   Fl_Clock(int x,int y,int w,int h, const char *l = 0);
   
   /**
-   * Creates a new <tt>Fl_Clock</tt> widget.
-   * Create an <tt>Fl_Clock</tt> widget using the given position, 
+   * Creates a new Fl_Clock widget.
+   * Create an Fl_Clock widget using the given position, 
    * size, and label string.
    *
    * \param[in] t boxtype
diff --git a/FL/Fl_Double_Window.H b/FL/Fl_Double_Window.H
index 5aac830f4..afca356db 100644
--- a/FL/Fl_Double_Window.H
+++ b/FL/Fl_Double_Window.H
@@ -37,11 +37,9 @@
   copy it to the on-screen window.
   <P>It is highly recommended that you put the following code before the
   first show() of <I>any</I> window in your program: </P>
-  <UL>
-  <PRE>
+  \code
   Fl::visual(FL_DOUBLE|FL_INDEX)
-  </PRE>
-  </UL>
+  \endcode
   This makes sure you can use Xdbe on servers where double buffering
   does not exist for every visual.
 */
diff --git a/FL/Fl_Free.H b/FL/Fl_Free.H
index 4d8147aca..05997e0b5 100644
--- a/FL/Fl_Free.H
+++ b/FL/Fl_Free.H
@@ -47,15 +47,13 @@ typedef int (*FL_HANDLEPTR)(Fl_Widget *, int , float, float, char);
   widgets.
   <P>There are five types of free, which determine when the handle
   function is called: </P>
-  <UL>
-  <PRE>
+  \code
   #define FL_NORMAL_FREE		1
   #define FL_SLEEPING_FREE	2
   #define FL_INPUT_FREE		3
   #define FL_CONTINUOUS_FREE	4
   #define FL_ALL_FREE		5
-  </PRE>
-  </UL>
+  \endcode
   <P>An FL_INPUT_FREE accepts FL_FOCUS events.  A FL_CONTINUOUS_FREE sets
   a timeout callback 100 times a second and provides a FL_STEP event,
   this has obvious detrimental effects on machine performance.
diff --git a/FL/Fl_Gl_Window.H b/FL/Fl_Gl_Window.H
index ce081973c..af7b5f910 100644
--- a/FL/Fl_Gl_Window.H
+++ b/FL/Fl_Gl_Window.H
@@ -85,7 +85,7 @@ public:
     after</I> draw() is called.  You can use this inside your 
     draw() method to avoid unneccessarily initializing the OpenGL
     context.  Just do this:
-    <UL><PRE>
+    \code
     void mywindow::draw() {
      if (!valid()) {
        glViewport(0,0,w(),h());
@@ -97,7 +97,7 @@ public:
      }
      ... draw your geometry here ...
     }
-    </PRE></UL>
+    \endcode
     
     You can turn valid() on by calling valid(1).  You
     should only do this after fixing the transformation inside a draw()
diff --git a/FL/Fl_Group.H b/FL/Fl_Group.H
index 2e4b8d7a8..635173fe0 100644
--- a/FL/Fl_Group.H
+++ b/FL/Fl_Group.H
@@ -170,8 +170,8 @@ public:
 /**
   This is a dummy class that allows you to end a Fl_Group in a constructor list of a
   class:
-  <UL>
-  <PRE>class MyClass {
+  \code 
+   class MyClass {
    Fl_Group group;
    Fl_Button button_in_group;
    Fl_End end;
@@ -183,8 +183,8 @@ public:
    button_in_group(20,20,60,30),
    end(),
    button_outside_group(10,120,60,30)
-  {}</PRE>
-  </UL>
+  {} 
+  \endcode
 */
 class FL_EXPORT Fl_End {
 public:
diff --git a/FL/Fl_Help_View.H b/FL/Fl_Help_View.H
index a6986efe3..eb469c514 100644
--- a/FL/Fl_Help_View.H
+++ b/FL/Fl_Help_View.H
@@ -204,9 +204,9 @@ public:
     for the file in question. It must return a pathname that can be
     opened as a local file or NULL:</P>
     
-    <UL><PRE>
+    \code
     const char *fn(Fl_Widget *w, const char *uri);
-    </PRE></UL>
+    \endcode
     
     <P>The link function can be used to retrieve remote or virtual
     documents, returning a temporary file that contains the actual
diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H
index 57331caba..e797865e2 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -54,8 +54,7 @@ class Fl_Menu_;
 /**
   The Fl_Menu_Item structure defines a single menu item that
   is used by the Fl_Menu_ class.  
-  <UL>
-  <PRE>
+  \code
   struct Fl_Menu_Item {
    const char*	        text; // label()
    ulong		shortcut_;
@@ -79,10 +78,9 @@ class Fl_Menu_;
    FL_MENU_DIVIDER	= 0x80,
    FL_MENU_HORIZONTAL	= 0x100
   };
-  </PRE>
-  </UL>
+  \endcode
   Typically menu items are statically defined; for example:
-  <UL><PRE>
+  \code
   Fl_Menu_Item popup[] = {
    {&quot;&alpha&quot;,   FL_ALT+'a', the_cb, (void*)1},
    {&quot;&beta&quot;,    FL_ALT+'b', the_cb, (void*)2},
@@ -101,7 +99,7 @@ class Fl_Menu_;
    {&quot;check&quot;,    FL_ALT+'i', 0, 0, FL_MENU_TOGGLE|FL_MENU_VALUE},
    {&quot;box&quot;,      FL_ALT+'i', 0, 0, FL_MENU_TOGGLE},
    {0}};
-  </PRE></UL>
+  \endcode
   produces:
   <P ALIGN=CENTER>\image html  menu.gif </P>
   
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 3eb3a95e6..bdaf6e4ec 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -41,12 +41,12 @@
 
 
 /**
-   <tt>Fl_Preferences </tt>provides methods to store user
+   Fl_Preferences provides methods to store user
    settings between application starts. It is similar to the
    Registry on WIN32 and Preferences on MacOS, and provides a
    simple configuration mechanism for UNIX.
    
-   <tt>Fl_Preferences </tt>uses a hierarchy to store data. It
+   Fl_Preferences uses a hierarchy to store data. It
    bundles similar data into groups and manages entries into those
    groups as name/value pairs.
    
@@ -82,18 +82,18 @@ public:
   /**
      The constructor creates a group that manages name/value pairs and
      child groups. Groups are ready for reading and writing at any time.
-     The <tt>root</tt> argument is either <tt>Fl_Preferences::USER</tt>
-     or <tt>Fl_Preferences::SYSTEM</tt>.
+     The root argument is either Fl_Preferences::USER
+     or Fl_Preferences::SYSTEM.
      
      This constructor creates the <i>base</i> instance for all
      following entries and reads existing databases into memory. The
-     <tt>vendor</tt> argument is a unique text string identifying the
+     vendor argument is a unique text string identifying the
      development team or vendor of an application.  A domain name or
      an EMail address are great unique names, e.g.
      "researchATmatthiasm.com" or "fltk.org". The
-     <tt>application</tt> argument can be the working title or final
-     name of your application. Both <tt>vendor</tt> and
-     <tt>application</tt> must be valid relative UNIX pathnames and
+     application argument can be the working title or final
+     name of your application. Both vendor and
+     application must be valid relative UNIX pathnames and
      may contain '/'s to create deeper file structures.
     
      \param[in] root can be USER or SYSTEM for user specific or system wide preferences
@@ -105,7 +105,7 @@ public:
   /**
      This constructor is used to create or read a preferences file at an
      arbitrary position in the file system. The file name is generated
-     as <tt><i>path</i>/<i>application</i>.prefs</tt>. If <i>application</i>
+     as <i>path</i>/<i>application</i>.prefs. If <i>application</i>
      is 0, <i>path</i> must contain the full file name.
      
      \param[in] path path to the directory that contains the preferences file
@@ -116,7 +116,7 @@ public:
 
   /**
      This constructor generates a new group of preference entries
-     inside the group or file <i>parent</i>. The <tt>group</tt> argument 
+     inside the group or file <i>parent</i>. The group argument 
      identifies a group of entries. It can contain '/'s to get quick 
      access to individual elements inside the hierarchy.
     
@@ -150,7 +150,7 @@ public:
   /**
      Returns the name of the Nth group. There is no guaranteed
      order  of group names. The index must be within the range given
-     by <tt>groups()</tt>.
+     by groups().
      
      \param[in] index number indexing the requested group
      \return cstring pointer to the group name
@@ -160,8 +160,8 @@ public:
   /**
      Returns non-zero if a group with this name exists.
      Groupnames are relative to the Preferences node and can contain a path.
-     <tt>"."</tt> describes the current node, <tt>"./"</tt> describes the topmost node.
-     By preceding a groupname with a <tt>"./"</tt>, its path becomes relative to the topmost node.
+     "." describes the current node, "./" describes the topmost node.
+     By preceding a groupname with a "./", its path becomes relative to the topmost node.
      
      \param[in] group name of group that is searched for
      \return 0 if group was not found
@@ -187,7 +187,7 @@ public:
   /**
      Returns the name of an entry. There is no guaranteed order of
      entry names. The index must be within the range given by
-     <tt>entries()</tt>.
+     entries().
     
      \param[in] index number indexing the requested entry
      \return pointer to value cstring
@@ -339,7 +339,7 @@ public:
      supplied. The return value indicates if the value was available
      (non-zero) or the default was used (0). get() allocates memory of
      sufficient size to hold the value. The buffer must be free'd by 
-     the developer using '<tt>free(value)</tt>'. 
+     the developer using 'free(value)'. 
     
      \param[in] entry name of entry
      \param[out] value returned from preferences or default value if none was set
@@ -352,7 +352,7 @@ public:
      Reads an entry from the group. A default value must be
      supplied. The return value indicates if the value was available
      (non-zero) or the default was used (0). 
-     '<tt>maxSize</tt>' is the maximum length of text that will be read. 
+     'maxSize' is the maximum length of text that will be read. 
      The text buffer must allow for one additional byte for a trailling zero.
     
      \param[in] entry name of entry
@@ -368,7 +368,7 @@ public:
      supplied. The return value indicates if the value was available
      (non-zero) or the default was used (0). get() allocates memory of
      sufficient size to hold the value. The buffer must be free'd by 
-     the developer using '<tt>free(value)</tt>'. 
+     the developer using 'free(value)'. 
     
      \param[in] entry name of entry
      \param[out] value returned from preferences or default value if none was set
@@ -382,7 +382,7 @@ public:
      Reads an entry from the group. A default value must be
      supplied. The return value indicates if the value was available
      (non-zero) or the default was used (0). 
-     '<tt>maxSize</tt>' is the maximum length of text that will be read. 
+     'maxSize' is the maximum length of text that will be read. 
     
      \param[in] entry name of entry
      \param[out] value returned from preferences or default value if none was set
@@ -429,11 +429,11 @@ public:
      'Name' provides a simple method to create numerical or more complex 
      procedural names for entries and groups on the fly.
      
-     Example: <tt>prefs.set(Fl_Preferences::Name("File%d",i),file[i]);</tt>. 
+     Example: prefs.set(Fl_Preferences::Name("File%d",i),file[i]);. 
     
-     See <tt>test/preferences.cxx</tt> as a sample for writing arrays into preferences.<p>
+     See test/preferences.cxx as a sample for writing arrays into preferences.<p>
      'Name' is actually implemented as a class inside Fl_Preferences. It casts
-     into <tt>const char*</tt> and gets automatically destroyed after the enclosing call
+     into const char* and gets automatically destroyed after the enclosing call
      ends.
    */
   class FL_EXPORT Name {
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index b23b5ba61..5f8f0c4e6 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -344,7 +344,7 @@ public:
    *  The label is shown somewhere on or next to the widget. The passed pointer 
    *  is stored unchanged in the widget (the string is \em not copied), so if 
    *  you need to set the label to a formatted value, make sure the buffer is 
-   *  <tt>static</tt>, global, or allocated. The copy_label() method can be used 
+   *  static, global, or allocated. The copy_label() method can be used 
    *  to make a copy of the label string automatically.
    *  \param[in] text pointer to new label text
    *  \see copy_label()
@@ -466,13 +466,13 @@ public:
   /** Sets the current tooltip text. 
    *  Sets a string of text to display in a popup tooltip window when the user 
    *  hovers the mouse over the widget. The string is <I>not</I> copied, so 
-   *  make sure any formatted string is stored in a <TT>static</TT>, global, 
+   *  make sure any formatted string is stored in a static, global, 
    *  or allocated buffer.
    * 
    *  If no tooltip is set, the tooltip of the parent is inherited. Setting a 
    *  tooltip for a group and setting no tooltip for a child will show the 
    *  group's tooltip instead. To avoid this behavior, you can set the child's 
-   *  tooltip to an empty string (<tt>&quot;&quot;</tt>).
+   *  tooltip to an empty string (&quot;&quot;).
    *  \param[in] t new tooltip
    */
   void tooltip(const char *t);
@@ -510,14 +510,14 @@ public:
   void callback(Fl_Callback1*cb, long p=0) {callback_=(Fl_Callback*)cb; user_data_=(void*)p;}
 
   /** Gets the user data for this widget.
-   *  Gets the current user data (<TT>void *</TT>) argument
+   *  Gets the current user data (void *) argument
    *  that is passed to the callback function.
    *  \return user data as a pointer
    */
   void* user_data() const {return user_data_;}
 
   /** Sets the user data for this widget.
-   *  Sets the new user data (<TT>void *</TT>) argument
+   *  Sets the new user data (void *) argument
    *  that is passed to the callback function.
    *  \param[in] v new user data
    */
@@ -573,11 +573,11 @@ public:
   Fl_When when() const {return (Fl_When)when_;}
 
   /** Flags used to decide when a callback is called.
-   *  <TT>Fl_Widget::when()</TT> is a set of bitflags used by subclasses of 
-   *  <TT> Fl_Widget</TT> to decide when to do the callback.  If the value 
+   *  Fl_Widget::when() is a set of bitflags used by subclasses of 
+   *   Fl_Widget to decide when to do the callback.  If the value 
    *  is zero then the callback is never done.  Other values are described 
    *  in the individual widgets.  This field is in the base class so that 
-   *  you can scan a panel and <TT>do_callback()</TT> on all the ones that 
+   *  you can scan a panel and do_callback() on all the ones that 
    *  don't do their own callbacks in response to an &quot;OK&quot; button.
    *  \param[in] i set of flags 
    */
@@ -597,15 +597,15 @@ public:
 
   /** Makes a widget visible.
    *  An invisible widget never gets redrawn and does not get events.  
-   *  The <TT>visible()</TT> method returns true if the widget is set to be  
-   *  visible. The <TT>visible_r()</TT> method returns true if the widget and 
+   *  The visible() method returns true if the widget is set to be  
+   *  visible. The visible_r() method returns true if the widget and 
    *  all of its parents are visible. A widget is only visible if 
-   *  <TT>visible()</TT> is true on it <I>and all of its parents</I>. 
+   *  visible() is true on it <I>and all of its parents</I>. 
    * 
-   *  Changing it will send <TT>FL_SHOW</TT> or <TT>FL_HIDE</TT> events to 
+   *  Changing it will send FL_SHOW or FL_HIDE events to 
    *  the widget. <I>Do not change it if the parent is not visible, as this 
-   *  will send false <TT>FL_SHOW</TT> or <TT>FL_HIDE</TT> events to the 
-   *  widget</I>. <TT>redraw()</TT> is called if necessary on this or the parent.
+   *  will send false FL_SHOW or FL_HIDE events to the 
+   *  widget</I>. redraw() is called if necessary on this or the parent.
    *  
    *  \see hide(), visible(), visible_r()
    */
@@ -684,8 +684,8 @@ public:
   void clear_output() {flags_ &= ~OUTPUT;}
 
   /** Returns if the widget is able to take events.
-   *  This is the same as <TT>(active() && !output()
-   *  && visible())</TT> but is faster.
+   *  This is the same as (active() && !output()
+   *  && visible()) but is faster.
    *  \retval 0 if the widget takes no events
    */ 
   int takesevents() const {return !(flags_&(INACTIVE|INVISIBLE|OUTPUT));}
@@ -716,8 +716,8 @@ public:
 
   /** Give the widget the keyboard focus.
    *  Tries to make this widget be the Fl::focus() widget, by first sending 
-   *  it an <TT>FL_FOCUS</TT> event, and if it returns non-zero, setting 
-   *  <TT>Fl::focus()</TT> to this widget.  You should use this method to 
+   *  it an FL_FOCUS event, and if it returns non-zero, setting 
+   *  Fl::focus() to this widget.  You should use this method to 
    *  assign the focus to a widget.  
    *  \return true if the widget accepted the focus.
    */
@@ -851,7 +851,7 @@ public:
 
   /** Returns a pointer to the primary Fl_Window widget.
    *  \retval  NULL if no window is associated with this widget.  
-   *  \note for an <TT>Fl_Window</TT> widget, this returns its <I>parent</I> window (if any), not <I>this</I> window.
+   *  \note for an Fl_Window widget, this returns its <I>parent</I> window (if any), not <I>this</I> window.
    */
   Fl_Window* window() const ;
 
diff --git a/src/Fl.cxx b/src/Fl.cxx
index 92183b54b..e403ab3af 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -186,57 +186,11 @@ static void elapse_timeouts() {
 // time interval:
 static double missed_timeout_by;
 
-/**
-  Add a one-shot timeout callback.  The function will be called by
-  Fl::wait() at <i>t</i> seconds after this function is called.
-  The optional void* argument is passed to the callback.
-  
-  <P>You can have multiple timeout callbacks. To remove an timeout
-  callback use Fl::remove_timeout().
-  
-  <p>If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to
-  reschedule the subsequent timeouts.</p>
-  
-  <p>The following code will print &quot;TICK&quot; each second on
-  stdout with a fair degree of accuracy:</p>
-  
-  <PRE>
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
-  </PRE>
-*/
 void Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *argp) {
   elapse_timeouts();
   repeat_timeout(time, cb, argp);
 }
 
-/**
-  This method repeats a timeout callback from the expiration of the
-  previous timeout, allowing for more accurate timing. You may only call
-  this method inside a timeout callback.
-  
-  <p>The following code will print &quot;TICK&quot; each second on
-  stdout with a fair degree of accuracy:</p>
-  
-  <PRE>
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
-  </PRE>
-*/
 void Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *argp) {
   time += missed_timeout_by; if (time < -.05) time = 0;
   Timeout* t = free_timeout;
@@ -316,7 +270,7 @@ static Check *first_check, *next_check, *free_check;
   
   <p>Sample code:
   
-  <UL><PRE>
+  \code
   bool state_changed; // anything that changes the display turns this on
   
   void callback(void*) {
@@ -330,7 +284,7 @@ static Check *first_check, *next_check, *free_check;
    Fl::add_check(callback);
    return Fl::run();
   }
-  </PRE></UL>
+  \endcode
 */
 void Fl::add_check(Fl_Timeout_Handler cb, void *argp) {
   Check* t = free_check;
@@ -543,13 +497,13 @@ int Fl::wait() {
   Same as Fl::wait(0).  Calling this during a big calculation
   will keep the screen up to date and the interface responsive:
   
-  <UL><PRE>
+  \code
   while (!calculation_done()) {
   calculate();
   Fl::check();
   if (user_hit_abort_button()) break;
   }
-  </PRE></UL>
+  \endcode
   
   <P>The returns non-zero if any windows are displayed, and 0 if no
   windows are displayed (this is likely to change in future versions of
@@ -567,7 +521,7 @@ int Fl::check() {
   true if Fl::check() would do anything (it will continue to
   return true until you call Fl::check() or Fl::wait()).
   
-  <UL><PRE>
+  \code
   while (!calculation_done()) {
   calculate();
   if (Fl::ready()) {
@@ -576,7 +530,7 @@ int Fl::check() {
     if (user_hit_abort_button()) break;
   }
   }
-  </PRE></UL>
+  \endcode
 */
 int Fl::ready() {
 #if ! defined( WIN32 )  &&  ! defined(__APPLE__)
@@ -1537,9 +1491,11 @@ void Fl::delete_widget(Fl_Widget *wi) {
   num_dwidgets ++;
 }
 
-
-void
-Fl::do_widget_deletion() {
+/** 
+    Deletes widgets previously scheduled for deletion.
+    See void Fl::delete_widget(Fl_Widget *wi) 
+*/
+void Fl::do_widget_deletion() {
   if (!num_dwidgets) return;
 
   for (int i = 0; i < num_dwidgets; i ++)
@@ -1551,7 +1507,9 @@ Fl::do_widget_deletion() {
 static Fl_Widget ***widget_watch = 0;
 static int num_widget_watch = 0;
 static int max_widget_watch = 0;
-
+/** Adds a widget pointer to the watch list. 
+   \todo explain the role of the watch list, 
+   it may be related to invalid widget deletion crash fixes... */
 void Fl::watch_widget_pointer(Fl_Widget *&w) 
 {
   Fl_Widget **wp = &w;
@@ -1572,6 +1530,7 @@ void Fl::watch_widget_pointer(Fl_Widget *&w)
   widget_watch[num_widget_watch++] = wp;
 }
 
+/** Releases a widget pointer to the watch list */
 void Fl::release_widget_pointer(Fl_Widget *&w)
 {
   Fl_Widget **wp = &w;
@@ -1583,7 +1542,7 @@ void Fl::release_widget_pointer(Fl_Widget *&w)
     }
   }
 }
-
+/** Clears a widget pointer in the watch list */
 void Fl::clear_widget_pointer(Fl_Widget const *w) 
 {
   if (w==0L) return;
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index 8447ab080..be0c8ebd4 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -118,9 +118,9 @@
   "Description text (patterns)" or just "patterns". A file chooser
   that provides filters for HTML and image files might look like:
   
-  <UL><PRE>
+  \code
   "HTML Files (*.html)\tImage Files (*.{bmp,gif,jpg,png})"
-  </PRE></UL>
+  \endcode
   
   <P>The file chooser will automatically add the "All Files (*)"
   pattern to the end of the string you pass if you do not provide
@@ -253,13 +253,13 @@
   Fl_File_Chooser::count().
   
   <P>This sample code loops through all selected files:
-  <PRE>
+  \code
   // Get list of filenames user selected from a MULTI chooser
   for ( int t=1; t&lt;=chooser-&gt;count(); t++ ) {
      const char *filename = chooser-&gt;value(t);
      ..
   }
-  </PRE>
+  \endcode
 */
 
 /** \fn const char *Fl_File_Chooser::value(int file)
diff --git a/src/Fl_File_Icon2.cxx b/src/Fl_File_Icon2.cxx
index 303c0e1f5..119954949 100644
--- a/src/Fl_File_Icon2.cxx
+++ b/src/Fl_File_Icon2.cxx
@@ -581,9 +581,9 @@ int Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
   FileChooser widget and should be used when the application
   starts:
   
-  <UL><PRE>
+  \code
   Fl_File_Icon::load_system_icons();
-  </PRE></UL>
+  \endcode
 */
 void
 Fl_File_Icon::load_system_icons(void) {
diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx
index 1edb61394..9265fe7b5 100644
--- a/src/Fl_Menu_add.cxx
+++ b/src/Fl_Menu_add.cxx
@@ -207,19 +207,19 @@ int Fl_Menu_Item::add(
   <P>Shortcut can be 0L, or either a modifier/key combination (for example
   FL_CTRL+'A') or a string describing the shortcut in one of two ways:</p>
   
-  <pre>
+  \code
    [#+^]&lt;ascii_value&gt;    eg. "97", "^97", "+97", "#97"
    [#+^]&lt;ascii_char&gt;     eg. "a", "^a", "+a", "#a"
-  </pre>
+  \endcode
   ..where &lt;ascii_value&gt; is a decimal value representing an
   ascii character (eg. 97 is the ascii for 'a'), and the optional
   prefixes enhance the value  that follows. Multiple prefixes must
   appear in the above order.
-  <pre>
+  \code
    # - Alt
    + - Shift
    ^ - Control
-  </pre>
+  \endcode
   Text shortcuts are converted to integer shortcut by calling 
   int fl_old_shortcut(const char*).
   
diff --git a/src/fl_boxtype.cxx b/src/fl_boxtype.cxx
index ec7490e30..e98a203ec 100644
--- a/src/fl_boxtype.cxx
+++ b/src/fl_boxtype.cxx
@@ -51,7 +51,8 @@ static uchar inactive_ramp[24] = {
   49, 49, 50, 50,
   51, 51, 52, 52};
 static int draw_it_active = 1;
-
+/** Determines if the current draw box is active or inactive. 
+    If inactive, the box color is changed by the inactive color. */
 int Fl::draw_box_active() { return draw_it_active; }
 
 uchar *fl_gray_ramp() {return (draw_it_active?active_ramp:inactive_ramp)-'A';}
@@ -275,12 +276,12 @@ int Fl::box_dx(Fl_Boxtype t) {return fl_box_table[t].dx;}
     respectively.
     
     <P>An example to compute the area inside a widget's box():
-    <pre>
+    \code
          int X = yourwidget-&gt;x() + Fl::box_dx(yourwidget-&gt;box());
          int Y = yourwidget-&gt;y() + Fl::box_dy(yourwidget-&gt;box());
          int W = yourwidget-&gt;w() - Fl::box_dw(yourwidget-&gt;box());
          int H = yourwidget-&gt;h() - Fl::box_dh(yourwidget-&gt;box());
-    </pre>
+    \endcode
     <P>These functions are mainly useful in the draw() code 
     for deriving custom widgets, where one wants to avoid drawing 
     over the widget's own border box().
diff --git a/src/fl_utf.c b/src/fl_utf.c
index c3e80f7f2..95b4e37c6 100644
--- a/src/fl_utf.c
+++ b/src/fl_utf.c
@@ -81,7 +81,7 @@ static unsigned short cp1252[32] = {
     standards recommend), adding a test to see if the length is
     unexpectedly 1 will work:
 
-\code
+    \code
     if (*p & 0x80) { // what should be a multibyte encoding
       code = fl_utf8decode(p,end,&len);
       if (len<2) code = 0xFFFD; // Turn errors into REPLACEMENT CHARACTER
@@ -89,7 +89,7 @@ static unsigned short cp1252[32] = {
       code = *p;
       len = 1;
     }
-\endcode
+    \endcode
 
     Direct testing for the 1-byte case (as shown above) will also
     speed up the scanning of strings where the majority of characters
diff --git a/src/forms_free.cxx b/src/forms_free.cxx
index ec5346299..950fe4730 100644
--- a/src/forms_free.cxx
+++ b/src/forms_free.cxx
@@ -44,30 +44,26 @@ void Fl_Free::step(void *v) {
 /**
     The constructor takes both the type and the handle
     function. The handle function should be declared as follows:
-    <UL>
-    <PRE>
+    \code
     int
     handle_function(Fl_Widget *w,
                    int       event,
     	        float     event_x,
     		float     event_y,
     		char      key)
-    </PRE>
-    </UL>
+    \endcode
     This function is called from the the handle() method in
     response to most events, and is called by the draw() method.
     The event argument contains the event type:
-    <UL>
-    <PRE>
+    \code
     // old event names for compatibility:
     #define FL_MOUSE		FL_DRAG
-    #define FL_DRAW			0
-    #define FL_STEP			9
+    #define FL_DRAW		0
+    #define FL_STEP		9
     #define FL_FREEMEM		12
     #define FL_FREEZE		FL_UNMAP
-    #define FL_THAW			FL_MAP
-    </PRE>
-    </UL>
+    #define FL_THAW		FL_MAP
+    \endcode
 */
 Fl_Free::Fl_Free(uchar t,int X, int Y, int W, int H,const char *l,
 		 FL_HANDLEPTR hdl) :
diff --git a/src/gl_start.cxx b/src/gl_start.cxx
index 868a0d894..8275399a1 100644
--- a/src/gl_start.cxx
+++ b/src/gl_start.cxx
@@ -109,19 +109,6 @@ void gl_finish() {
   glXWaitGL();
 #endif
 }
-/**
-    This does the same thing as
-    Fl::visual(int) but also
-    requires OpenGL drawing to work.  This <I>must</I> be done if
-    you want to draw in normal windows with OpenGL with  gl_start() and
-    gl_end().  It may be useful to call this so your X
-    windows use the same visual as an
-    Fl_Gl_Window, which on
-    some servers will reduce colormap flashing.
-    
-    <P>See Fl_Gl_Window
-    for a list of additional values for the argument.
-*/
 int Fl::gl_visual(int mode, int *alist) {
   Fl_Gl_Choice *c = Fl_Gl_Choice::find(mode,alist);
   if (!c) return 0;