Updated some documentation for Fl_Preferences::getUserdataPath()

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

FL/Fl_Preferences.H

@@ -401,18 +401,34 @@ public:
    */
   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
-   */
-  char getUserdataPath( char *path, int pathlen );
+  \brief Creates a path that is related to the preferences file and
+  that is usable for additional application data.
 
+  This function creates a directory that is named after the preferences
+  database without the \c .prefs extension and located in the same directory.
+  It then fills the given buffer with the complete path name.
+
+  Exmaple:
+  \code
+   Fl_Preferences prefs( USER, "matthiasm.com", "test" );
+   char path[FL_PATH_MAX];
+   prefs.getUserdataPath( path );
+  \endcode
+  creates the preferences database in (MS Windows):
+  \code
+  c:/Documents and Settings/matt/Application Data/matthiasm.com/test.prefs
+  \endcode
+  and returns the userdata path:
+  \code
+  c:/Documents and Settings/matt/Application Data/matthiasm.com/test/
+  \endcode
+    
+  \param[out] path buffer for user data path
+  \param[in] pathlen size of path buffer (should be at least \c FL_PATH_MAX)
+  \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

src/Fl_Preferences.cxx

@@ -484,20 +484,6 @@ int Fl_Preferences::size( const char *key )
   return v ? strlen( v ) : 0 ;
 }
 
-/**
- * creates a path that is related to the preferences file
- * and that is usable for application data beyond what is covered 
- * by Fl_Preferences.
- * - 'getUserdataPath' actually creates the directory
- * - 'path' must be large enough to receive a complete file path
- * example:
- *   Fl_Preferences prefs( USER, "matthiasm.com", "test" );
- *   char path[FL_PATH_MAX];
- *   prefs.getUserdataPath( path );
- * sample returns:
- *   Win32: c:/Documents and Settings/matt/Application Data/matthiasm.com/test/
- *   prefs: c:/Documents and Settings/matt/Application Data/matthiasm.com/test.prefs
- */
 char Fl_Preferences::getUserdataPath( char *path, int pathlen )
 {
   if ( rootNode )