Fixed some documentation for Fl_Preferences and fl_make_path.

2 files changed, 22 insertions, 6 deletions

diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index d30ed2e7b..3c4bb8feb 100644
--- a/src/Fl_Preferences.cxx
+++ b/src/Fl_Preferences.cxx
@@ -794,24 +794,37 @@ int Fl_Preferences::size( const char *key ) {
  database without the \c .prefs extension and located in the same directory.
  It then fills the given buffer with the complete path name.
 
+ There is no way to verify that the path name fit into the buffer.
+ If the name is too long, it will be clipped.
+
+ This function can be used with direct paths that don't end in \c .prefs .
+ \a getUserDataPath() will remove any extension and end the path with a \c / . If
+ the file name has no extension, \a getUserDataPath() will append \c .data/
+ to the path name.
+
  Example:
  \code
  Fl_Preferences prefs( USER, "matthiasm.com", "test" );
  char path[FL_PATH_MAX];
- prefs.getUserdataPath( path );
+ prefs.getUserdataPath( path, FL_PATH_MAX );
  \endcode
- ..creates the preferences database in (MS Windows):
+ creates the preferences database in the directory (User 'matt' on Linux):
  \code
- c:/Documents and Settings/matt/Application Data/matthiasm.com/test.prefs
+ /Users/matt/.fltk/matthiasm.com/test.prefs
  \endcode
  ..and returns the userdata path:
  \code
- c:/Documents and Settings/matt/Application Data/matthiasm.com/test/
+ /Users/matt/.fltk/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
+ \param[in] pathlen size of path buffer (should be at least \c FL_PATH_MAX )
+ \return 1 if there is no filename (\a path will be unmodified)
+ \return 1 if \a pathlen is 0 (\a path will be unmodified)
+ \return 1 if a path was created successfully, \a path will contain the path name ending in a '/'
+ \return 0 if path was not created for some reason;  \a path will contain the pathname that could not be created
+
+ \see Fl_Preferences::Fl_Preferences(Root, const char*, const char*)
  */
 char Fl_Preferences::getUserdataPath( char *path, int pathlen ) {
   if ( rootNode )
diff --git a/src/fl_utf8.cxx b/src/fl_utf8.cxx
index 7f40a6bb8..c0f681e49 100644
--- a/src/fl_utf8.cxx
+++ b/src/fl_utf8.cxx
@@ -544,6 +544,9 @@ int fl_rename(const char* f, const char *n) {
 
   This function creates a \p path in the file system by recursively creating
   all directories.
+
+  \param[in] path a Unix style ('/' forward slashes) absolute or relative pathname
+  \return 1 if the path was created, 0 if creating the path failed at some point
 */
 char fl_make_path( const char *path ) {
   if (fl_access(path, 0)) {