Updated some documentation for Fl_Preferences::getUserdataPath()

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

1 files changed, 25 insertions, 9 deletions

diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 2cc91785d..5caeaeeb5 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -401,19 +401,35 @@ 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.
+  \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
-     \return 0 if path was not created or pathname can't fit into buffer
-   */
+  \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
      the base preference group. This function is rarely used as