Doxygen Documentation WP6 Done, Also completed the documentation of Help_View, Help_Dialog and cleaned up Preferences from ugly stars in comments and also removed redundant get/set text from methods doc. In this increment, we don't bother with the old dox format (comments in header). We have better things to do with our time (like about 40 mores files to doxyfy :-).

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

3 files changed, 306 insertions, 260 deletions

diff --git a/FL/Fl_Help_View.H b/FL/Fl_Help_View.H
index 22613874f..a6986efe3 100644
--- a/FL/Fl_Help_View.H
+++ b/FL/Fl_Help_View.H
@@ -90,10 +90,11 @@ struct Fl_Help_Target
   int		y;		// Y offset of target
 };
 
-//
-// Fl_Help_View class...
-//
-
+/**
+  The Fl_Help_View widget displays HTML text. Most HTML 2.0
+  elements are supported, as well as a primitive implementation of tables.
+  GIF, JPEG, and PNG images are displayed inline.
+*/
 class FL_EXPORT Fl_Help_View : public Fl_Group	//// Help viewer widget
 {
   enum { RIGHT = -1, CENTER, LEFT };	// Alignments
@@ -187,29 +188,64 @@ public:
 
   Fl_Help_View(int xx, int yy, int ww, int hh, const char *l = 0);
   ~Fl_Help_View();
+  /**    This method returns the current directory for the text in the buffer.  */
   const char	*directory() const { if (directory_[0]) return (directory_);
   					else return ((const char *)0); }
+  /**    This method returns the current filename for the text in the buffer.  */
   const char	*filename() const { if (filename_[0]) return (filename_);
   					else return ((const char *)0); }
   int		find(const char *s, int p = 0);
+  /**
+    This method assigns a callback function to use when a link is
+    followed or a file is loaded (via
+    Fl_Help_View::load()) that requires a different
+    file or path. The callback function receives a pointer to the
+    Fl_Help_View widget and the URI or full pathname
+    for the file in question. It must return a pathname that can be
+    opened as a local file or NULL:</P>
+    
+    <UL><PRE>
+    const char *fn(Fl_Widget *w, const char *uri);
+    </PRE></UL>
+    
+    <P>The link function can be used to retrieve remote or virtual
+    documents, returning a temporary file that contains the actual
+    data. If the link function returns NULL, the value of
+    the Fl_Help_View widget will remain unchanged.</P>
+    
+    <P>If the link callback cannot handle the URI scheme, it should
+    return the uri value unchanged or set the value() of the widget
+    before returning NULL.
+  */
   void		link(Fl_Help_Func *fn) { link_ = fn; }
   int		load(const char *f);
   void		resize(int,int,int,int);
+  /** Gets the size of the Help view */
   int		size() const { return (size_); }
   void		size(int W, int H) { Fl_Widget::size(W, H); }
+  /** Sets the default text color. */
   void		textcolor(Fl_Color c) { if (textcolor_ == defcolor_) textcolor_ = c; defcolor_ = c; }
+  /** Returns    the current default text color. */
   Fl_Color	textcolor() const { return (defcolor_); }
+  /** Sets the default text font. */
   void		textfont(Fl_Font f) { textfont_ = f; format(); }
+  /** Returns the current default text font. */
   Fl_Font       textfont() const { return (textfont_); }
+  /** Sets the default text size. */
   void		textsize(Fl_Fontsize s) { textsize_ = s; format(); }
+  /** Gets the default text size. */
   Fl_Fontsize  textsize() const { return (textsize_); }
+  /** Returns the current document title, or NULL if there is no title. */
   const char	*title() { return (title_); }
   void		topline(const char *n);
   void		topline(int);
+  /** Returns the current top line in pixels.  */
   int		topline() const { return (topline_); }
   void		leftline(int);
+  /** Gets the left position. */
   int		leftline() const { return (leftline_); }
   void		value(const char *v);
+  /** Returns the current buffer contents. */
   const char	*value() const { return (value_); }
   void          clear_selection();
   void          select_all();
diff --git a/FL/Fl_Light_Button.H b/FL/Fl_Light_Button.H
index b9da5b440..41471b681 100644
--- a/FL/Fl_Light_Button.H
+++ b/FL/Fl_Light_Button.H
@@ -30,6 +30,16 @@
 
 #include "Fl_Button.H"
 
+/**
+  <P>This subclass displays the &quot;on&quot; state by turning on a light, 
+  rather than drawing pushed in.  The shape of the  &quot;light&quot; 
+  is initially set to FL_DOWN_BOX.  The color of the light when
+  on is controlled with selection_color(), which defaults to FL_YELLOW.
+
+  Buttons generate callbacks when they are clicked by the user.  You
+  control exactly when and how by changing the values for type() and when().
+  <P ALIGN=CENTER>\image html Fl_Light_Button.gif</P>
+*/
 class FL_EXPORT Fl_Light_Button : public Fl_Button {
 protected:
     virtual void draw();
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 292d5a18a..3eb3a95e6 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -26,7 +26,7 @@
 //
 
 /** \file
- * Preferences definitions for the Fast Light Tool Kit (FLTK).
+   Preferences definitions for the Fast Light Tool Kit (FLTK).
  */
 
 #ifndef Fl_Preferences_H
@@ -41,29 +41,29 @@
 
 
 /**
- * <tt>Fl_Preferences </tt>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
- * bundles similar data into groups and manages entries into those
- * groups as name/value pairs.
- * 
- * Preferences are stored in text files that can be edited
- * manually. The file format is easy to read and relatively
- * forgiving. Preferences files are the same on all platforms. User
- * comments in preference files are preserved. Filenames are unique
- * for each application by using a vendor/application naming
- * scheme. The user must provide default values for all entries to
- * ensure proper operation should preferences be corrupted or not
- * yet exist.
- * 
- * Entries can be of any length. However, the size of each
- * preferences file should be kept under 100k for performance
- * reasons. One application can have multiple preferences files.
- * Extensive binary data however should be stored in separate
- * files; see getUserdataPath().
+   <tt>Fl_Preferences </tt>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
+   bundles similar data into groups and manages entries into those
+   groups as name/value pairs.
+   
+   Preferences are stored in text files that can be edited
+   manually. The file format is easy to read and relatively
+   forgiving. Preferences files are the same on all platforms. User
+   comments in preference files are preserved. Filenames are unique
+   for each application by using a vendor/application naming
+   scheme. The user must provide default values for all entries to
+   ensure proper operation should preferences be corrupted or not
+   yet exist.
+   
+   Entries can be of any length. However, the size of each
+   preferences file should be kept under 100k for performance
+   reasons. One application can have multiple preferences files.
+   Extensive binary data however should be stored in separate
+   files; see getUserdataPath().
  */
 class FL_EXPORT Fl_Preferences 
 {
@@ -71,7 +71,7 @@ class FL_EXPORT Fl_Preferences
 public:
 
   /**
-   * Define the scope of the preferences.
+     Define the scope of the preferences.
    */
   enum Root { 
     SYSTEM=0,   ///< Preferences are used system-wide
@@ -80,345 +80,345 @@ public:
   // enum Type { win32, macos, fltk };
 
   /**
-   * 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>.
-   * 
-   * 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
-   * 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
-   * may contain '/'s to create deeper file structures.
-   *
-   * \param[in] root can be USER or SYSTEM for user specific or system wide preferences
-   * \param[in] vendor unique text describing the company or author of this file
-   * \param[in] application unique text describing the application
+     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>.
+     
+     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
+     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
+     may contain '/'s to create deeper file structures.
+    
+     \param[in] root can be USER or SYSTEM for user specific or system wide preferences
+     \param[in] vendor unique text describing the company or author of this file
+     \param[in] application unique text describing the application
    */
   Fl_Preferences( Root root, const char *vendor, const char *application );
 
   /**
-   * 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>
-   * is 0, <i>path</i> must contain the full file name.
-   * 
-   * \param[in] path path to the directory that contains the preferences file
-   * \param[in] vendor unique text describing the company or author of this file
-   * \param[in] application unique text describing the application
+     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>
+     is 0, <i>path</i> must contain the full file name.
+     
+     \param[in] path path to the directory that contains the preferences file
+     \param[in] vendor unique text describing the company or author of this file
+     \param[in] application unique text describing the application
    */
   Fl_Preferences( const char *path, const char *vendor, const char *application );
 
   /**
-   * This constructor generates a new group of preference entries
-   * inside the group or file <i>parent</i>. The <tt>group</tt> argument 
-   * identifies a group of entries. It can contain '/'s to get quick 
-   * access to individual elements inside the hierarchy.
-   *
-   * \param[in] parent reference object for the new group
-   * \param[in] group name of the group to access (may contain '/'s)
+     This constructor generates a new group of preference entries
+     inside the group or file <i>parent</i>. The <tt>group</tt> argument 
+     identifies a group of entries. It can contain '/'s to get quick 
+     access to individual elements inside the hierarchy.
+    
+     \param[in] parent reference object for the new group
+     \param[in] group name of the group to access (may contain '/'s)
    */
   Fl_Preferences( Fl_Preferences &parent, const char *group );
 
   /**
-   * \see Fl_Preferences( Fl_Preferences&, const char *group )
+     \see Fl_Preferences( Fl_Preferences&, const char *group )
    */
   Fl_Preferences( Fl_Preferences*, const char *group );
 
   /**
-   * The destructor removes allocated resources. When used on the
-   * <i>base</i> preferences group, the destructor flushes all
-   * changes to the preferences file and deletes all internal
-   * databases.
+     The destructor removes allocated resources. When used on the
+     <i>base</i> preferences group, the destructor flushes all
+     changes to the preferences file and deletes all internal
+     databases.
    */
   ~Fl_Preferences();
 
 
   /**
-   * Returns the number of groups that are contained within a
-   * group.
-   *
-   * \return 0 for no groups at all
+     Returns the number of groups that are contained within a
+     group.
+    
+     \return 0 for no groups at all
    */
   int groups();
 
   /**
-   * 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>.
-   * 
-   * \param[in] index number indexing the requested group
-   * \return cstring pointer to the group name
+     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>.
+     
+     \param[in] index number indexing the requested group
+     \return cstring pointer to the group name
    */
   const char *group( int index );
   
   /**
-   * 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.
-   * 
-   * \param[in] group name of group that is searched for
-   * \return 0 if group was not found
+     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.
+     
+     \param[in] group name of group that is searched for
+     \return 0 if group was not found
    */
   char groupExists( const char *group );
 
   /**
-   * Deletes a group.
-   *
-   * \param[in] group name of the group to delete
-   * \return 0 if call failed
+     Deletes a group.
+    
+     \param[in] group name of the group to delete
+     \return 0 if call failed
    */
   char deleteGroup( const char *group );
 
 
   /**
-   * Returns the number of entries (name/value pairs) in a group.
-   *
-   * \return number of entries
+     Returns the number of entries (name/value pairs) in a group.
+    
+     \return number of entries
    */
   int entries();
 
   /**
-   * 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>.
-   *
-   * \param[in] index number indexing the requested entry
-   * \return pointer to value cstring
+     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>.
+    
+     \param[in] index number indexing the requested entry
+     \return pointer to value cstring
    */
   const char *entry( int index );
 
   /**
-   * Returns non-zero if an entry with this name exists.
-   * 
-   * \param[in] entry name of entry that is searched for
-   * \return 0 if entry was not found
+     Returns non-zero if an entry with this name exists.
+     
+     \param[in] entry name of entry that is searched for
+     \return 0 if entry was not found
    */
   char entryExists( const char *entry );
   
   /**
-   * Removes a single entry (name/value pair).
-   *
-   * \param[in] entry name of entry to delete
-   * \return 0 if deleting the entry failed
+     Removes a single entry (name/value pair).
+    
+     \param[in] entry name of entry to delete
+     \return 0 if deleting the entry failed
    */
   char deleteEntry( const char *entry );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \return 0 if setting the value failed
    */
   char set( const char *entry, int value );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \return 0 if setting the value failed
    */
   char set( const char *entry, float value );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \param[in] precision number of decimal digits to represent value
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \param[in] precision number of decimal digits to represent value
+     \return 0 if setting the value failed
    */
   char set( const char *entry, float value, int precision );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \return 0 if setting the value failed
    */
   char set( const char *entry, double value );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \param[in] precision number of decimal digits to represent value
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \param[in] precision number of decimal digits to represent value
+     \return 0 if setting the value failed
    */
   char set( const char *entry, double value, int precision );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \return 0 if setting the value failed
    */
   char set( const char *entry, const char *value );
 
   /** 
-   * Sets an entry (name/value pair). The return value indicates if there
-   * was a problem storing the data in memory. However it does not
-   * reflect if the value was actually stored in the preferences
-   * file.
-   *
-   * \param[in] entry name of entry
-   * \param[in] value set this entry to \a value
-   * \param[in] size of data array
-   * \return 0 if setting the value failed
+     Sets an entry (name/value pair). The return value indicates if there
+     was a problem storing the data in memory. However it does not
+     reflect if the value was actually stored in the preferences
+     file.
+    
+     \param[in] entry name of entry
+     \param[in] value set this entry to \a value
+     \param[in] size of data array
+     \return 0 if setting the value failed
    */
   char set( const char *entry, const void *value, int size ); 
 
 
   /**
-   * 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).
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \return 0 if the default value was used 
+     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).
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \return 0 if the default value was used 
    */
   char get( const char *entry, int &value,    int defaultValue );
 
   /**
-   * 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). 
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \return 0 if the default value was used 
+     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). 
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \return 0 if the default value was used 
    */
   char get( const char *entry, float &value,  float defaultValue );
 
   /**
-   * 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). 
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \return 0 if the default value was used 
+     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). 
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \return 0 if the default value was used 
    */
   char get( const char *entry, double &value, double defaultValue );
 
   /**
-   * 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). get() allocates memory of
-   * sufficient size to hold the value. The buffer must be free'd by 
-   * the developer using '<tt>free(value)</tt>'. 
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \return 0 if the default value was used 
+     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). get() allocates memory of
+     sufficient size to hold the value. The buffer must be free'd by 
+     the developer using '<tt>free(value)</tt>'. 
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \return 0 if the default value was used 
    */
   char get( const char *entry, char *&value,  const char *defaultValue );
 
   /**
-   * 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. 
-   * The text buffer must allow for one additional byte for a trailling zero.
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \param[in] maxSize maximum length of value plus one byte for a trailing zero
-   * \return 0 if the default value was used 
+     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. 
+     The text buffer must allow for one additional byte for a trailling zero.
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \param[in] maxSize maximum length of value plus one byte for a trailing zero
+     \return 0 if the default value was used 
    */
   char get( const char *entry, char *value,   const char *defaultValue, int maxSize );
 
   /**
-   * 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). get() allocates memory of
-   * sufficient size to hold the value. The buffer must be free'd by 
-   * the developer using '<tt>free(value)</tt>'. 
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \param[in] defaultSize size of default value array
-   * \return 0 if the default value was used 
+     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). get() allocates memory of
+     sufficient size to hold the value. The buffer must be free'd by 
+     the developer using '<tt>free(value)</tt>'. 
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \param[in] defaultSize size of default value array
+     \return 0 if the default value was used 
    */
   char get( const char *entry, void *&value,  const void *defaultValue, int defaultSize );
 
   /**
-   * 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. 
-   *
-   * \param[in] entry name of entry
-   * \param[out] value returned from preferences or default value if none was set
-   * \param[in] defaultValue default value to be used if no preference was set
-   * \param[in] defaultSize size of default value array
-   * \param[in] maxSize maximum length of value
-   * \return 0 if the default value was used 
-   *
-   * \todo maxSize should receive the number of bytes that were read.
+     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. 
+    
+     \param[in] entry name of entry
+     \param[out] value returned from preferences or default value if none was set
+     \param[in] defaultValue default value to be used if no preference was set
+     \param[in] defaultSize size of default value array
+     \param[in] maxSize maximum length of value
+     \return 0 if the default value was used 
+    
+     \todo maxSize should receive the number of bytes that were read.
    */
   char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int maxSize );
 
   /**
-   * Returns the size of the value part of an entry.
-   *
-   * \return size of value
+     Returns the size of the value part of an entry.
+    
+     \return size of value
    */
   int size( const char *entry );
 
 
   /**
-   * Creates a path that is related to the preferences file and
-   * that is usable for application data beyond what is covered by
-   * Fl_Preferences.
-   *
-   * \param[out] path buffer for user data path
-   * \param[in] pathlen size of path buffer
-   * \return 0 if path was not created or pathname can't fit into buffer
+     Creates a path that is related to the preferences file and
+     that is usable for application data beyond what is covered by
+     Fl_Preferences.
+    
+     \param[out] path buffer for user data path
+     \param[in] pathlen size of path buffer
+     \return 0 if path was not created or pathname can't fit into buffer
    */
   char getUserdataPath( char *path, int pathlen );
 
 
   /**
-   * Write all preferences to disk. This function works only with
-   * the base preference group. This function is rarely used as
-   * deleting the base preferences flushes automatically.
+     Write all preferences to disk. This function works only with
+     the base preference group. This function is rarely used as
+     deleting the base preferences flushes automatically.
    */
   void flush();
 
@@ -426,15 +426,15 @@ public:
   // char import( const char *filename );
 
   /**
-   * '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>. 
-   *
-   * See <tt>test/preferences.cxx</tt> 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
-   * ends.
+     '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>. 
+    
+     See <tt>test/preferences.cxx</tt> 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
+     ends.
    */
   class FL_EXPORT Name {
 
@@ -443,18 +443,18 @@ public:
   public:
 
     /**
-     * Create a numerical name.
+       Create a numerical name.
      */
     Name( unsigned int n );
 
     /**
-     * Create a name using 'printf' style formatting.
+       Create a name using 'printf' style formatting.
      */
     Name( const char *format, ... );
 
     /**
-     * Return the Name as a c-string.
-     * \internal
+       Return the Name as a c-string.
+       \internal
      */
     operator const char *() { return data_; }
     ~Name();