Moving some doxygen dox around (Fl_Preferences).

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

1 files changed, 99 insertions, 52 deletions

diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index 87d95e37a..3a94f0295 100644
--- a/src/Fl_Preferences.cxx
+++ b/src/Fl_Preferences.cxx
@@ -56,15 +56,26 @@ char Fl_Preferences::nameBuffer[128];
 
 
 /**
- * create the initial preferences base
- * - root: machine or user preferences
- * - vendor: unique identification of author or vendor of application
- *     Must be a valid directory name.
- * - application: vendor unique application name, i.e. "PreferencesTest"
- *     multiple preferences files can be created per application.
- *     Must be a valid file name.
- * example: Fl_Preferences base( Fl_Preferences::USER, "fltk.org", "test01");
- */
+   The constructor creates a group that manages name/value pairs and
+   child groups. Groups are ready for reading and writing at any time.
+   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
+   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
+   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 \c USER or \c 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::Fl_Preferences( Root root, const char *vendor, const char *application )
 {
   node = new Node( "." );
@@ -73,9 +84,16 @@ Fl_Preferences::Fl_Preferences( Root root, const char *vendor, const char *appli
 
 
 /**
- * create the initial preferences base
- * - path: an application-supplied path
- * example: Fl_Preferences base( "/usr/foo" );
+   \brief Use this constructor to create or read a preferences file at an
+   arbitrary position in the file system. 
+
+   The file name is generated in the form
+   <tt><i>path</i>/<i>application</i>.prefs</tt>. If \a application
+   is \c NULL, \a path 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::Fl_Preferences( const char *path, const char *vendor, const char *application )
 {
@@ -85,41 +103,46 @@ Fl_Preferences::Fl_Preferences( const char *path, const char *vendor, const char
 
 
 /**
- * create a Preferences node in relation to a parent node for reading and writing
- * - parent: base name for group
- * - group: group name (can contain '/' seperated group names)
- * example: Fl_Preferences colors( base, "setup/colors" );
+   \brief Gnerate or read a new group of entries within another group. 
+
+   Use the \a group argument to name the group that you would like to access.
+   \a Group can also contain a path to a group further down the hierarchy by
+   seperating group names with a forward slash '/'. 
+
+   \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( Fl_Preferences &parent, const char *key )
+Fl_Preferences::Fl_Preferences( Fl_Preferences &parent, const char *group )
 {
   rootNode = parent.rootNode;
-  node = parent.node->addChild( key );
+  node = parent.node->addChild( group );
 }
 
 
 /**
- * create a Preferences node in relation to a parent node for reading and writing
- * - parent: base name for group
- * - group: group name (can contain '/' seperated group names)
- * example: Fl_Preferences colors( base, "setup/colors" );
+   \see Fl_Preferences( Fl_Preferences&, const char *group )
  */
-Fl_Preferences::Fl_Preferences( Fl_Preferences *parent, const char *key )
+Fl_Preferences::Fl_Preferences( Fl_Preferences *parent, const char *group )
 {
   rootNode = parent->rootNode;
-  node = parent->node->addChild( key );
+  node = parent->node->addChild( group );
 }
 
 
 /**
- * destroy individual keys
- * - destroying the base preferences will flush changes to the prefs file
- * - after destroying the base, none of the depending preferences must be read or written
+   The destructor removes allocated resources. When used on the
+   \em base preferences group, the destructor flushes all
+   changes to the preferences file and deletes all internal
+   databases.
+
+   The destructor does not remove any data from the database. It merely
+   deletes your reference to the database.
  */
 Fl_Preferences::~Fl_Preferences()
 {
   if (node && !node->parent()) delete rootNode;
   // DO NOT delete nodes! The root node will do that after writing the preferences
-  // zero all pointer to avoid memory errors, event though
+  // zero all pointer to avoid memory errors, even though
   // Valgrind does not complain (Cygwind does though)
   node = 0L;
   rootNode = 0L;
@@ -127,8 +150,10 @@ Fl_Preferences::~Fl_Preferences()
 
 
 /**
- * return the number of groups that are contained within a group
- * example: int n = base.groups();
+   Returns the number of groups that are contained within a
+   group.
+  
+   \return 0 for no groups at all
  */
 int Fl_Preferences::groups()
 {
@@ -137,10 +162,12 @@ int Fl_Preferences::groups()
 
 
 /**
- * return the group name of the n'th group
- * - there is no guaranteed order of group names
- * - the index must be within the range given by groups()
- * example: printf( "Group(%d)='%s'\n", ix, base.group(ix) );
+   Returns the name of the Nth group. There is no guaranteed
+   order  of group names. The index must be within the range given
+   by groups().
+     
+   \param[in] num_group number indexing the requested group
+   \return 'C' string pointer to the group name
  */
 const char *Fl_Preferences::group( int num_group )
 {
@@ -149,8 +176,13 @@ const char *Fl_Preferences::group( int num_group )
 
 
 /**
- * return 1, if a group with this name exists
- * example: if ( base.groupExists( "setup/colors" ) ) ...
+   Returns non-zero if a group with this name exists.
+   Group names are relative to the Preferences node and can contain a path.
+   "." describes the current node, "./" describes the topmost node.
+   By preceding a groupname with a "./", its path becomes relative to the topmost node.
+     
+   \param[in] key name of group that is searched for
+   \return 0 if no group by that name was found
  */
 char Fl_Preferences::groupExists( const char *key )
 {
@@ -159,20 +191,26 @@ char Fl_Preferences::groupExists( const char *key )
 
 
 /**
- * delete a group
- * example: setup.deleteGroup( "colors/buttons" );
+   Deletes a group.
+
+   Remove a group and all keys and groups within that group
+   from the database.
+   
+   \param[in] group name of the group to delete
+   \return 0 if call failed
  */
-char Fl_Preferences::deleteGroup( const char *key )
+char Fl_Preferences::deleteGroup( const char *group )
 {
-  Node *nd = node->search( key );
+  Node *nd = node->search( group );
   if ( nd ) return nd->remove();
   return 0;
 }
 
 
 /**
- * return the number of entries (name/value) pairs for a group
- * example: int n = buttonColor.entries();
+   Returns the number of entries (name/value pairs) in a group.
+  
+   \return number of entries
  */
 int Fl_Preferences::entries()
 {
@@ -181,20 +219,24 @@ int Fl_Preferences::entries()
 
 
 /**
- * return the name of an entry
- * - there is no guaranteed order of entry names
- * - the index must be within the range given by entries()
- * example: printf( "Entry(%d)='%s'\n", ix, buttonColor.entry(ix) );
+   Returns the name of an entry. There is no guaranteed order of
+   entry names. The index must be within the range given by
+   entries().
+    
+   \param[in] index number indexing the requested entry
+   \return pointer to value cstring
  */
-const char *Fl_Preferences::entry( int ix )
+const char *Fl_Preferences::entry( int index )
 {
-  return node->entry[ix].name;
+  return node->entry[index].name;
 }
 
 
 /**
- * return 1, if an entry with this name exists
- * example: if ( buttonColor.entryExists( "red" ) ) ...
+   Returns non-zero if an entry with this name exists.
+     
+   \param[in] key name of entry that is searched for
+   \return 0 if entry was not found
  */
 char Fl_Preferences::entryExists( const char *key )
 {
@@ -203,8 +245,13 @@ char Fl_Preferences::entryExists( const char *key )
 
 
 /**
- * remove a single entry (name/value pair)
- * example: buttonColor.deleteEntry( "red" );
+   Delete a single name/value pair.
+   
+   This function removes the entry from the
+   database.
+ 
+   \param[in] key name of entry to delete
+   \return 0 if deleting the entry failed
  */
 char Fl_Preferences::deleteEntry( const char *key )
 {