Doxygen documentation

+ Added a new Module section named : File names and URI utility funtions
+ updated the pdf file adequately



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

FL/filename.H

@@ -30,9 +30,12 @@
 
 #  include "Fl_Export.H"
 
-#  define FL_PATH_MAX 256 /* all buffers are this length */
+/** \addtogroup filenames File names and URI utility funtions 
+    @{ */
 
-FL_EXPORT const char *fl_filename_name(const char *);
+#  define FL_PATH_MAX 256 ///< all path buffers should use this length
+/** Gets the file name from a path. \return a pointer to the char after the last slash, or to \a filename if there is none. */
+FL_EXPORT const char *fl_filename_name(const char * filename);
 FL_EXPORT const char *fl_filename_ext(const char *);
 FL_EXPORT char *fl_filename_setext(char *to, int tolen, const char *ext);
 FL_EXPORT int fl_filename_expand(char *to, int tolen, const char *from);
@@ -41,7 +44,7 @@ FL_EXPORT int fl_filename_relative(char *to, int tolen, const char *from);
 FL_EXPORT int fl_filename_match(const char *name, const char *pattern);
 FL_EXPORT int fl_filename_isdir(const char *name);
 
-#  ifdef __cplusplus
+#  if defined(__cplusplus) && !defined(FL_DOXYGEN)
 /*
  * Under WIN32, we include filename.H from numericsort.c; this should probably change...
  */
@@ -91,18 +94,20 @@ struct dirent {char d_name[1];};
 #    include <dirent.h>
 #  endif
 
-#  ifdef __cplusplus
+#  if defined (__cplusplus)
 extern "C" {
 #  endif /* __cplusplus */
 
+#  if !defined(FL_DOXYGEN)
 FL_EXPORT int fl_alphasort(struct dirent **, struct dirent **);
 FL_EXPORT int fl_casealphasort(struct dirent **, struct dirent **);
 FL_EXPORT int fl_casenumericsort(struct dirent **, struct dirent **);
 FL_EXPORT int fl_numericsort(struct dirent **, struct dirent **);
+#  endif
 
-typedef int (Fl_File_Sort_F)(struct dirent **, struct dirent **);
+  typedef int (Fl_File_Sort_F)(struct dirent **, struct dirent **); ///< File sorting function. \see fl_filename_list()
 
-#  ifdef __cplusplus
+#  if defined(__cplusplus)
 }
 
 /*
@@ -120,6 +125,7 @@ FL_EXPORT int fl_filename_list(const char *d, struct dirent ***l,
 FL_EXPORT int	fl_open_uri(const char *uri, char *msg = (char *)0,
 		            int msglen = 0);
 
+#    ifndef FL_DOXYGEN
 /*
  * _fl_filename_isdir_quick() is a private function that checks for a
  * trailing slash and assumes that the passed name is a directory if
@@ -128,6 +134,7 @@ FL_EXPORT int	fl_open_uri(const char *uri, char *msg = (char *)0,
  * outside of FLTK...
  */
 int _fl_filename_isdir_quick(const char *name);
+#    endif
 
 #  endif /* __cplusplus */
 
@@ -151,6 +158,8 @@ int _fl_filename_isdir_quick(const char *name);
 
 #endif /* FL_FILENAME_H */
 
+/** @} */
+
 /*
  * End of "$Id$".
  */

documentation/Doxyfile

@@ -1240,7 +1240,8 @@ PREDEFINED             = FL_DOXYGEN \
                          HAVE_CAIRO \
                          HAVE_GL \
                          HAVE_GL_OVERLAY \
-                         FL_EXPORT:=
+                         FL_EXPORT:= \
+			 __cplusplus
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 

src/filename_absolute.cxx

@@ -54,6 +54,13 @@ inline int isdirsep(char c) {return c=='/' || c=='\\';}
 #define isdirsep(c) ((c)=='/')
 #endif
 
+/**
+ * Makes a filename absolute from a relative filename.
+ * \param[out] to resulting absolute filename
+ * \param[in]  tolen size of the absolute filename buffer 
+ * \param[in]  from relative filename
+ * \return 0 if no change, non zero otherwise
+ */
 int fl_filename_absolute(char *to, int tolen, const char *from) {
   if (isdirsep(*from) || *from == '|'
 #if defined(WIN32) || defined(__EMX__) && !defined(__CYGWIN__)
@@ -107,10 +114,13 @@ int fl_filename_absolute(char *to, int tolen, const char *from) {
   return 1;
 }
 
-/*
+/**
- * 'fl_filename_relative()' - Make a filename relative to the current working directory.
+ * Makes a filename relative to the current working directory.
+ * \param[out] to resulting relative filename
+ * \param[in]  tolen size of the relative filename buffer 
+ * \param[in]  from absolute filename
+ * \return 0 if no change, non zero otherwise
  */
-
 int					// O - 0 if no change, 1 if changed
 fl_filename_relative(char       *to,	// O - Relative filename
                      int        tolen,	// I - Size of "to" buffer

src/filename_expand.cxx

@@ -47,6 +47,13 @@ static inline int isdirsep(char c) {return c=='/' || c=='\\';}
 #define isdirsep(c) ((c)=='/')
 #endif
 
+/**
+ * Expands a filename coontaining shell variables.
+ * \param[out] to resulting expanded filename
+ * \param[in]  tolen size of the expanded filename buffer 
+ * \param[in]  from filename containing shell variables
+ * \return 0 if no change, non zero otherwise
+ */
 int fl_filename_expand(char *to,int tolen, const char *from) {
 
   char *temp = new char[tolen];

src/filename_ext.cxx

@@ -29,6 +29,11 @@
 
 #include <FL/filename.H>
 
+/**
+   Gets the extensions of a filename
+   \param[in] buf the filename to be parsed
+   \return a pointer to the extension (including '.') if any or NULL otherwise
+ */
 const char *fl_filename_ext(const char *buf) {
   const char *q = 0;
   const char *p = buf;

src/filename_isdir.cxx

@@ -47,6 +47,11 @@ int _fl_filename_isdir_quick(const char* n) {
   return fl_filename_isdir(n);
 }
 
+/**
+   Determines if a file exists and is a directory from its filename
+   \param[in] n the filename to parse
+   \return non zero if file exists and is a directory, zero otherwise
+*/
 int fl_filename_isdir(const char* n) {
   struct stat	s;
   char		fn[1024];

src/filename_list.cxx

@@ -50,6 +50,29 @@ int fl_casealphasort(struct dirent **a, struct dirent **b) {
 }
 
 
+/**
+   Portable and const-correct wrapper for the scandir() function. 
+   For each file in that directory a "dirent" structure is created. 
+   The only portable thing about a dirent is that dirent.d_name is the nul-terminated file name. 
+   An pointers array to these dirent's is created and a pointer to the array is returned in *list.
+   The number of entries is given as a return value. 
+   If there is an error reading the directory a number less than zero is returned, 
+   and errno has the reason; errno does not work under WIN32. 
+   \param[in] d the name of the directory to list.  It does not matter if it has a trailing slash.
+   \param[out] list table containing the resulting directory listing
+   \param[in] sort sorting functor:
+    - fl_alphasort: The files are sorted in ascending alphabetical order; 
+        upper and lowercase letters are compared according to their ASCII ordering  uppercase before lowercase.
+    - fl_casealphasort: The files are sorted in ascending alphabetical order; 
+        upper and lowercase letters are compared equally case is not significant.
+    - fl_casenumericsort: The files are sorted in ascending "alphanumeric" order, where an attempt is made 
+        to put unpadded numbers in consecutive order; upper and lowercase letters 
+        are compared equally case is not significant.
+    - fl_numericsort: The files are sorted in ascending "alphanumeric" order, where an attempt is made 
+        to put unpadded numbers in consecutive order; upper and lowercase letters are compared 
+        according to their ASCII ordering - uppercase before lowercase. 
+   \return the number of entries if no error, a negative value otherwise.
+*/
 int fl_filename_list(const char *d, dirent ***list,
                      Fl_File_Sort_F *sort) {
 #ifndef HAVE_SCANDIR

src/filename_match.cxx

@@ -29,6 +29,21 @@
 #include <FL/filename.H>
 #include <ctype.h>
 
+/**
+    Checks if a string \a s matches a pattern \a p. 
+    The following syntax is used for the pattern:
+    - * matches any sequence of 0 or more characters.
+    - ? matches any single character.
+    - [set] matches any character in the set. Set can contain any single characters, or a-z to represent a range. 
+      To match ] or - they must be the first characters. To match ^ or ! they must not be the first characters.
+    - [^set] or [!set] matches any character not in the set.
+    - {X|Y|Z} or {X,Y,Z} matches any one of the subexpressions literally.
+    - \\x quotes the character x so it has no special meaning.
+    - x all other characters must be matched exactly.
+    \param[in] s the string to check for a match
+    \param[in] p the string pattern 
+    \return non zero if the string matches the pattern
+*/
 int fl_filename_match(const char *s, const char *p) {
   int matched;
 

src/filename_setext.cxx

@@ -32,6 +32,10 @@
 #include <FL/filename.H>
 #include "flstring.h"
 
+/**
+   Replaces the extension in \a buf of max. size \a buflen with the extension in \a ext. 
+   \return buf itself for calling convenience.
+*/
 char *fl_filename_setext(char *buf, int buflen, const char *ext) {
   char *q = (char *)fl_filename_ext(buf);
   if (ext) {

src/fl_color.cxx

@@ -124,6 +124,8 @@ Fl_XColor fl_xmap[1][256];
 #    define fl_overlay 0
 #  endif
 
+/** \addtogroup  fl_attributes
+    @{ */
 ////////////////////////////////////////////////////////////////
 // Get an rgb color.  This is easy for a truecolor visual.  For
 // colormapped it picks the closest color out of the cube in the
@@ -472,7 +474,9 @@ Fl_Color fl_contrast(Fl_Color fg, Fl_Color bg) {
   else if (l2 > 127) return FL_BLACK;
   else return FL_WHITE;
 }
-
+/**
+   @}
+*/
 //
 // End of "$Id$".
 //

src/fl_open_uri.cxx

@@ -59,10 +59,8 @@ static int	run_program(const char *program, char **argv, char *msg, int msglen);
 
 
 /**
- * Open the specified URI.
+ * Opens the specified Uniform Resource Identifier (URI).
- *
+ * Uses an operating-system dependent program or interface. For URIs
- * fl_open_uri() opens the specified Uniform Resource Identifier (URI)
- * using an operating-system dependent program or interface. For URIs
  * using the "ftp", "http", or "https" schemes, the system default web
  * browser is used to open the URI, while "mailto" and "news" URIs are
  * typically opened using the system default mail reader and "file" URIs