Documenting QGCFileDialog.h

src/QGCFileDialog.h

@@ -27,20 +27,45 @@
 #include <QFileDialog>
 
 /// @file
-///     @brief Subclass of QFileDialog which re-implements the static public functions. The reason for this
-///             is that the QFileDialog implementations of these use the native os dialogs. On OSX these
-///             these can intermittently hang. So instead here we use the native dialogs. It also allows
-///             use to catch these dialogs for unit testing.
+///     @brief Subclass of <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html">QFileDialog</a>
 ///     @author Don Gagne <don@thegagnes.com>
 
+/*!
+     Subclass of <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html">QFileDialog</a> which re-implements the static public functions. The reason for this
+     is that the <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html">QFileDialog</a> implementations of these use the native os dialogs. On OSX these
+     these can intermittently hang. So instead here we use the native dialogs. It also allows
+     use to catch these dialogs for unit testing.
+*/
+
 class QGCFileDialog : public QFileDialog {
     
 public:
+
+    //! Static helper that will return an existing directory selected by the user.
+    /*!
+      \param parent The parent QWidget.
+      \param caption The caption displayed at the top of the dialog.
+      \param dir The initial directory shown to the user.
+      \param options Set the various options that affect the look and feel of the dialog.
+      \return The chosen path or QString("") if none.
+      \sa <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html#getExistingDirectory">QFileDialog::getExistingDirectory()</a>
+    */
     static QString getExistingDirectory(QWidget* parent = 0,
                                         const QString& caption = QString(),
                                         const QString& dir = QString(),
                                         Options options = ShowDirsOnly);
     
+    //! Static helper that invokes a File Open dialog where the user can select a file to be opened.
+    /*!
+      \param parent The parent QWidget.
+      \param caption The caption displayed at the top of the dialog.
+      \param dir The initial directory shown to the user.
+      \param filter The filter used for selecting the file type.
+      \param selectedFilter **NOT IMPLEMENTED** Returns the filter that the user selected in the file dialog.
+      \param options Set the various options that affect the look and feel of the dialog.
+      \return The full path and filename to be opened or QString("") if none.
+      \sa <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html#getOpenFileName">QFileDialog::getOpenFileName()</a>
+    */
     static QString getOpenFileName(QWidget* parent = 0,
                                    const QString& caption = QString(),
                                    const QString& dir = QString(),
@@ -48,6 +73,17 @@ public:
                                    QString* selectedFilter = 0,
                                    Options options = 0);
     
+    //! Static helper that invokes a File Open dialog where the user can select one or more files to be opened.
+    /*!
+      \param parent The parent QWidget.
+      \param caption The caption displayed at the top of the dialog.
+      \param dir The initial directory shown to the user.
+      \param filter The filter used for selecting the file type.
+      \param selectedFilter **NOT IMPLEMENTED** Returns the filter that the user selected in the file dialog.
+      \param options Set the various options that affect the look and feel of the dialog.
+      \return A QStringList object containing zero or more files to be opened.
+      \sa <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html#getOpenFileNames">QFileDialog::getOpenFileNames()</a>
+    */
     static QStringList getOpenFileNames(QWidget* parent = 0,
                                         const QString& caption = QString(),
                                         const QString& dir = QString(),
@@ -55,9 +91,18 @@ public:
                                         QString* selectedFilter = 0,
                                         Options options = 0);
     
-    /// @brief getSaveFileName with an extra (optional) argument to define the extension (suffix) to
-    ///        be added if none is given by the user. If set, don't add the preceding period (i.e.
-    ///        use "mavlink" instead of ".mavlink")
+    //! Static helper that invokes a File Save dialog where the user can select a directory and enter a filename to be saved.
+    /*!
+      \param parent The parent QWidget.
+      \param caption The caption displayed at the top of the dialog.
+      \param dir The initial directory shown to the user.
+      \param filter The filter used for selecting the file type.
+      \param selectedFilter **NOT IMPLEMENTED** Returns the filter that the user selected in the file dialog.
+      \param options Set the various options that affect the look and feel of the dialog.
+      \param defaultSuffix Specifies a string that will be added to the filename if it has no suffix already. The suffix is typically used to indicate the file type (e.g. "txt" indicates a text file).
+      \return The full path and filename to be used to save the file or QString("") if none.
+      \sa <a href="http://qt-project.org/doc/qt-4.8/qfiledialog.html#getSaveFileName">QFileDialog::getSaveFileName()</a>
+    */
     static QString getSaveFileName(QWidget* parent = 0,
                                    const QString& caption = QString(),
                                    const QString& dir = QString(),