From ed80d9cef0c321012c65c31104be66dc64bf2fad Mon Sep 17 00:00:00 2001
From: Matthias Melcher <git@matthiasm.com>
Date: Tue, 14 Jan 2020 19:21:58 +0100
Subject: Fixed some documentation for Fl_Preferences and fl_make_path.

---
 FL/Fl_Preferences.H    | 15 +++++----------
 src/Fl_Preferences.cxx | 25 +++++++++++++++++++------
 src/fl_utf8.cxx        |  3 +++
 3 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 45717265a..eff8e1aae 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -50,21 +50,16 @@
    preferences file should be kept small for performance
    reasons. One application can have multiple preferences files.
    Extensive binary data however should be stored in separate
-   files: see getUserdataPath().
+   files: see \a Fl_Preferences::getUserdataPath() .
  
- \note Platform-specific location of the Fl_Preferences text files.
- This construct
-  \code new Fl_Preferences(Fl_Preferences::USER, "vendor", "application"); \endcode
- where "vendor" and "application" are any user-chosen strings, will create these text files:
- \li Windows XP platform: <tt>C:\\Documents and Settings\\<i>username</i>\\Application Data\\<i>vendor</i>\\<i>application</i>.prefs</tt>
- \li Windows 7+ platform: <tt>C:\\Users\\<i>username</i>\\AppData\\Roaming\\<i>vendor</i>\\<i>application</i>.prefs </tt>
- \li X11 platform: <tt>$HOME/.fltk/<i>vendor</i>/<i>application</i>.prefs </tt>
- \li MacOS platform: <tt>$HOME/Library/Preferences/<i>vendor</i>/<i>application</i>.prefs </tt>
-
    \note Starting with FLTK 1.3, preference databases are expected to
    be in UTF-8 encoding. Previous databases were stored in the
    current character set or code page which renders them incompatible
    for text entries using international characters.
+
+   \note Starting with FLTK 1.4, searching a valid path to store the preferences
+   files has changed slightly. Please see <i>Fl_Preferences::Fl_Preferences(Root, const char*, const char*)</i>
+   for details.
  */
 class FL_EXPORT Fl_Preferences {
 
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)) {
-- 
cgit v1.2.3