From 00ed897277139be1b03ac90afcf45af3105f2d47 Mon Sep 17 00:00:00 2001
From: Manolo Gouy <Manolo>
Date: Fri, 19 Oct 2012 11:23:51 +0000
Subject: [PATCH] Documented the fl_open() utility function.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@9704 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 FL/Fl_Native_File_Chooser.H    |  7 ++++---
 FL/filename.H                  |  3 +++
 documentation/src/osissues.dox |  6 +++---
 src/Fl_File_Chooser2.cxx       |  9 +++++----
 src/fl_utf8.cxx                | 10 ++++++++++
 5 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/FL/Fl_Native_File_Chooser.H b/FL/Fl_Native_File_Chooser.H
index 32e500c6f..442f03958 100644
--- a/FL/Fl_Native_File_Chooser.H
+++ b/FL/Fl_Native_File_Chooser.H
@@ -84,9 +84,10 @@
  \endcode
  
  The Fl_Native_File_Chooser widget transmits UTF-8 encoded filenames to its user. It is
- recommended to open files that may have non-ASCII names with the fl_fopen() utility 
- function that handles these names in a cross-platform way (whereas the standard 
- fopen() function fails on the MSWindows platform to open files with a non-ASCII name).
+ recommended to open files that may have non-ASCII names with the fl_fopen() or
+ fl_open() utility functions that handle these names in a cross-platform way 
+ (whereas the standard fopen()/open() functions fail on the MSWindows platform 
+ to open files with a non-ASCII name).
  
  <B>Platform Specific Caveats</B>
  
diff --git a/FL/filename.H b/FL/filename.H
index 6ef9b9b7e..f5c87bc6a 100644
--- a/FL/filename.H
+++ b/FL/filename.H
@@ -15,6 +15,9 @@
  *
  *     http://www.fltk.org/str.php
  */
+/** \file
+ File names and URI utility functions.
+ */
 
 /* Xcode on OS X includes files by recursing down into directories.
  * This code catches the cycle and directly includes the required file.
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index 58d960896..e72398e7f 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -475,9 +475,9 @@ state information and data structures.
 
 \subsection non_ascii_filenames Using filenames with non-ASCII characters
 
-In FLTK, all strings, including filenames, are UTF-8 encoded. The utility function
-fl_fopen() allows to open files potentially having non-ASCII names in a 
-cross-platform fashion, whereas the standard fopen() function fails to do so.
+In FLTK, all strings, including filenames, are UTF-8 encoded. The utility functions
+fl_fopen() and fl_open() allow to open files potentially having non-ASCII names in a 
+cross-platform fashion, whereas the standard fopen()/open() functions fail to do so.
 
 \subsection osissues_win32_messages Handling Other WIN32 Messages
 
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index d192f636e..eddbbb5d2 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -28,10 +28,11 @@
   \image latex  Fl_File_Chooser.jpg "Fl_File_Chooser" width=12cm
  
  The Fl_File_Chooser widget transmits UTF-8 encoded filenames to its user. It is
- recommended to open files that may have non-ASCII names with the fl_fopen() utility 
- function that handles these names in a cross-platform way (whereas the standard 
- fopen() function fails on the MSWindows platform to open files with a non-ASCII name).
-  
+ recommended to open files that may have non-ASCII names with the fl_fopen() or
+ fl_open() utility functions that handle these names in a cross-platform way 
+ (whereas the standard fopen()/open() functions fail on the MSWindows platform 
+ to open files with a non-ASCII name).
+ 
   The Fl_File_Chooser class also exports several static values
   that may be used to localize or customize the appearance of all file chooser
   dialogs:
diff --git a/src/fl_utf8.cxx b/src/fl_utf8.cxx
index 3b2f9a553..c76a4b01e 100644
--- a/src/fl_utf8.cxx
+++ b/src/fl_utf8.cxx
@@ -518,6 +518,15 @@ char *fl_getenv(const char* v)
 #endif
 }
 
+/** Cross-platform function to open files with a UTF-8 encoded name.
+ 
+ This function is especially useful under the MSWindows platform where the 
+ standard open() function fails with UTF-8 encoded non-ASCII filenames.
+ \param f  the UTF-8 encoded filename
+ \param oflags  other arguments are as in the standard open() function
+ \return  a file descriptor upon successful completion, or -1 in case of error.
+ \sa fl_fopen().
+ */
 int fl_open(const char* f, int oflags, ...)
 {
 	int pmode;
@@ -548,6 +557,7 @@ int fl_open(const char* f, int oflags, ...)
  \param f  the UTF-8 encoded filename
  \param mode  same as the second argument of the standard fopen() function
  \return  a FILE pointer upon successful completion, or NULL in case of error.
+ \sa fl_open().
  */
 FILE *fl_fopen(const char* f, const char *mode)
 {