From fc28028954130e77fbb2c527203c55eab0cf250d Mon Sep 17 00:00:00 2001
From: Matthias Melcher <fltk@matthiasm.com>
Date: Sat, 18 Oct 2008 20:35:13 +0000
Subject: 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    | 34 +++++++++++++++++++++++++---------
 src/Fl_Preferences.cxx | 14 --------------
 2 files changed, 25 insertions(+), 23 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
diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index 684cceac0..87d95e37a 100644
--- a/src/Fl_Preferences.cxx
+++ b/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 )
-- 
cgit v1.2.3