Clarify Fl_File_Chooser documentation

src/Fl_File_Chooser2.cxx

@@ -3,20 +3,26 @@
 //
 // More Fl_File_Chooser routines.
 //
-// Copyright 1999-2018 by Michael Sweet.
+// Copyright 1999-2007 by Michael Sweet.
+// Copyright 2008-2020 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
 // file is missing or damaged, see the license at:
 //
-//     http://www.fltk.org/COPYING.php
+//     https://www.fltk.org/COPYING.php
 //
 // Please report all bugs and problems on the following page:
 //
-//     http://www.fltk.org/str.php
+//     https://www.fltk.org/str.php
 //
 
-// fabien: ATTENTION: Only Out Of Source Gen. because cxx/H files are autogenerated by fluid.
+// The following documentation is placed here because the implementation and
+// header files FL/Fl_File_Chooser.H and src/Fl_File_Chooser.cxx are generated
+// by fluid from src/Fl_File_Chooser.fl.
+
+// *** BEGIN OUT OF SOURCE DOCUMENTATION ***
+
 /** \defgroup group_comdlg Common Dialogs classes and functions
     @{
 */
@@ -111,8 +117,7 @@
 
   The Fl_File_Chooser class also exports the Fl_File_Chooser::newButton
   and Fl_File_Chooser::previewButton widgets so that application developers
-  can control their appearance and use.  For more complex customization,
+  can control their appearance and use.
-  consider copying the FLTK file chooser code and changing it accordingly.
 */
 /** @} */
 
@@ -250,28 +255,45 @@
 /** \fn int Fl_File_Chooser::visible()
   Returns 1 if the Fl_File_Chooser window is visible.*/
 
-/** \fn Fl_Widget* Fl_File_Chooser::add_extra(Fl_Widget*)
+/** \fn Fl_Widget *Fl_File_Chooser::add_extra(Fl_Widget *extra)
-  Adds extra widget at the bottom of Fl_File_Chooser window.
+  Adds an extra widget at the bottom of the Fl_File_Chooser window.
-  Returns pointer for previous extra widget or NULL if not set previously.
+
-  If argument is NULL only remove previous extra widget.
+  You can use any Fl_Widget or Fl_Group. If you use an Fl_Group, set its (x, y)
+  coordinates to (0, 0) and position its children relative to (0, 0) inside
+  the Fl_Group container widget. Make sure that all child widgets of the
+  Fl_Group are entirely included inside the bounding box of their parents,
+  i.e. the Fl_Group widget, and the Fl_File_Chooser window, respectively.
+
+  \note The width of the Fl_File_Chooser window is an undocumented
+    implementation detail and may change in the future.
 
-  \note Fl_File_Chooser does \b not delete extra widget in destructor!
+  If \p extra is NULL any previous extra widget is removed.
-     To prevent memory leakage, don't forget to delete unused extra widgets
+
+  \param[in] extra Custom widget or group to be added to the Fl_File_Chooser window.
+
+  \returns Pointer to previous extra widget or NULL if not set previously.
+
+  \note Fl_File_Chooser does \b not delete the extra widget in its destructor!
+    The extra widget is removed from the Fl_File_Chooser window before the
+    Fl_File_Chooser widget gets destroyed. To prevent memory leakage, don't
+    forget to delete unused extra widgets.
 */
   /** \fn int Fl_File_Chooser::shown()
-    Returns non-zero if the file chooser main window show() has been called (but not hide()
+    Returns non-zero if the file chooser main window show() has been called,
-    see Fl_Window::shown()
+    but not hide().
+    \see Fl_Window::shown()
   */
 
   /** \fn void Fl_File_Chooser::callback(void (*cb)(Fl_File_Chooser *, void *), void *d = 0)
-    Sets the file chooser callback cb and associated data d */
+    Sets the file chooser callback cb and associated data \p d */
 
   /** \fn void Fl_File_Chooser::user_data(void *d)
-    Sets the file chooser user data d */
+    Sets the file chooser user data \p d */
 
   /** \fn void * Fl_File_Chooser::user_data() const
-    Gets the file chooser user data */
+    Gets the file chooser user data. */
-// *** END OF OUT OF SOURCE DOC ***
+
+// *** END OF OUT OF SOURCE DOCUMENTATION ***
 
 // Contents:
 //
@@ -290,12 +312,7 @@
 //   quote_pathname()                     - Quote a pathname for a menu.
 //   unquote_pathname()                   - Unquote a pathname from a menu.
 //
-//   Fl_File_Chooser::add_extra()         - add extra widget at the bottom, return pointer 
+//   Fl_File_Chooser::add_extra()         - add custom extra widget or group
-//                                          to previous extra widget or NULL if none,
-//                                          If argument is NULL extra widget removed.
-//                                          NOTE! file chooser does't delete extra widget in 
-//                                          destructor! To prevent memory leakage don't forget
-//					    delete unused extra widgets by yourself.
 //
 
 //