Solves issue #856: improve Fl_File_Chooser enum docs

FL/Fl_File_Chooser.H

@@ -42,7 +42,18 @@
 
 class FL_EXPORT Fl_File_Chooser {
 public:
-  enum { SINGLE = 0, MULTI = 1, CREATE = 2, DIRECTORY = 4 };
+  /**
+    \enum Type
+    Determines the type of file chooser presented to the user.
+  */
+  enum Type {
+    SINGLE    = 0, ///< Select a single, existing file.
+    MULTI     = 1, ///< Select one or more existing files.
+    CREATE    = 2, ///< When used alone, select a single, existing file or specify a new filename.
+                   ///< Can be combined with DIRECTORY (e.g. CREATE|DIRECTORY) to have the same
+                   ///< effect for directories.
+    DIRECTORY = 4  ///< Select a single, existing directory. Can be combined with CREATE.
+  };
 private:
   static Fl_Preferences *prefs_;
   void (*callback_)(Fl_File_Chooser*, void *);

src/Fl_File_Chooser2.cxx

@@ -150,37 +150,30 @@
 
 /** \fn Fl_File_Chooser::Fl_File_Chooser(const char *pathname, const char *pattern, int type, const char *title)
   The constructor creates the Fl_File_Chooser dialog shown.
-  The pathname argument can be a directory name or a
+
+  - The \p pathname argument can be a directory name or a
   complete file name (in which case the corresponding file is highlighted
   in the list and in the filename input field.)
 
-  The pattern argument can be a NULL
+  - The \p pattern argument can be a NULL
   string or "*" to list all files, or it can be a
   series of descriptions and filter strings separated by tab
   characters (\\t). The format of filters is either
   "Description text (patterns)" or just "patterns". A file chooser
   that provides filters for HTML and image files might look like:
-
   \code
   "HTML Files (*.html)\tImage Files (*.{bmp,gif,jpg,png})"
   \endcode
-
   The file chooser will automatically add the "All Files (*)"
   pattern to the end of the string you pass if you do not provide
   one. The first filter in the string is the default filter.
-
+  \p
   See the FLTK documentation on fl_filename_match()
   for the kinds of pattern strings that are supported.
 
-  The type argument can be one of the following:
+  - The \p type argument can be one of the Fl_File_Chooser::Type values.
 
-  \li \c SINGLE - allows the user to select a single, existing file.
-  \li \c MULTI - allows the user to select one or more existing files.
-  \li \c CREATE - allows the user to select a single, existing file or
-         specify a new filename.
-  \li \c DIRECTORY - allows the user to select a single, existing directory.
-
-  The title argument is used to set the title bar text for the
+  - The \p title argument is used to set the title bar text for the
   Fl_File_Chooser window.
 */
 
@@ -1425,8 +1418,8 @@ Fl_File_Chooser::update_preview()
  \code
  // Get list of filenames user selected from a MULTI chooser
  for ( int t=1; t<=chooser->count(); t++ ) {
- const char *filename = chooser->value(t);
- ...
+     const char *filename = chooser->value(t);
+     ...
  }
  \endcode
  */