Documentation: BaseFileWizard.

src/plugins/coreplugin/basefilewizard.cpp

@@ -61,6 +61,17 @@
 
 enum { debugWizard = 0 };
 
+/*!
+    \class Core::GeneratedFile
+    \brief Represents a file generated by a wizard.
+
+    The Wizard class will check for each file whether it already exists and will
+    report any errors that may occur during creation of the files.
+
+    \sa Core::BaseFileWizardParameters, Core::BaseFileWizard, Core::StandardFileWizard
+    \sa Core::Internal::WizardEventLoop
+ */
+
 namespace Core {
 
 class GeneratedFilePrivate : public QSharedData
@@ -230,6 +241,15 @@ void BaseFileWizardParameterData::clear()
     displayCategory.clear();
 }
 
+/*!
+    \class Core::BaseFileWizardParameters
+    \brief Parameter class for passing parameters to instances of class Wizard
+     containing name, icon and such.
+
+    \sa Core::GeneratedFile, Core::BaseFileWizard, Core::StandardFileWizard
+    \sa Core::Internal::WizardEventLoop
+*/
+
 BaseFileWizardParameters::BaseFileWizardParameters(IWizard::WizardKind kind) :
    m_d(new BaseFileWizardParameterData(kind))
 {
@@ -336,15 +356,24 @@ void BaseFileWizardParameters::setDisplayCategory(const QString &v)
     m_d->displayCategory = v;
 }
 
-/* WizardEventLoop: Special event loop that runs a QWizard and terminates if the page changes.
+/*!
- * Synopsis:
+    \class Core::Internal::WizardEventLoop
- * \code
+    \brief Special event loop that runs a QWizard and terminates if the page changes.
+
+    Use by Core::BaseFileWizard to intercept the change from the standard wizard pages
+    to the extension pages (as the latter require the list of Core::GeneratedFile generated).
+
+    Synopsis:
+    \code
     Wizard wizard(parent);
     WizardEventLoop::WizardResult wr;
     do {
         wr = WizardEventLoop::execWizardPage(wizard);
     } while (wr == WizardEventLoop::PageChanged);
- * \endcode */
+    \endcode
+
+    \sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::BaseFileWizard, Core::StandardFileWizard
+*/
 
 class WizardEventLoop : public QEventLoop
 {
@@ -422,7 +451,24 @@ void WizardEventLoop::rejected()
     quit();
 }
 
-// ---------------- BaseFileWizardPrivate
+/*!
+    \class Core::BaseFileWizard
+    \brief A generic wizard for creating files.
+
+    The abstract methods:
+    \list
+    \o createWizardDialog(): Called to create the QWizard dialog to be shown
+    \o generateFiles(): Generate file content
+    \endlist
+
+    must be implemented.
+    The behaviour can be further customized by overwriting the virtual method \c postGenerateFiles(),
+    which is called after generating the files.
+
+    \sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::StandardFileWizard
+    \sa Core::Internal::WizardEventLoop
+*/
+
 struct BaseFileWizardPrivate
 {
     explicit BaseFileWizardPrivate(const Core::BaseFileWizardParameters &parameters)
@@ -587,7 +633,27 @@ void BaseFileWizard::runWizard(const QString &path, QWidget *parent)
         QMessageBox::critical(0, tr("File Generation Failure"), errorMessage);
 }
 
-// Write
+/*!
+    \fn virtual QWizard *Core::BaseFileWizard::createWizardDialog(QWidget *parent,
+                                                                  const QString &defaultPath,
+                                                                  const WizardPageList &extensionPages) const = 0
+    \brief Implement to create the wizard dialog on the parent, adding the extension pages.
+*/
+
+/*!
+    \fn virtual Core::GeneratedFiles Core::BaseFileWizard::generateFiles(const QWizard *w,
+                                                                         QString *errorMessage) const = 0
+     \brief Overwrite to query the parameters from the dialog and generate the files.
+
+     Note: This does not generate physical files, but merely the list of Core::GeneratedFile.
+*/
+
+/*!
+    \brief Physically write files.
+
+    Re-implement (calling the base implementation) to create files with CustomGeneratorAttribute set.
+*/
+
 bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessage)
 {
     foreach (const GeneratedFile &generatedFile, files)
@@ -597,6 +663,9 @@ bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessa
     return true;
 }
 
+/*!
+    \brief Sets some standard options on a QWizard
+*/
 
 void BaseFileWizard::setupWizard(QWizard *w)
 {
@@ -605,6 +674,11 @@ void BaseFileWizard::setupWizard(QWizard *w)
     w->setOption(QWizard::NoBackButtonOnStartPage, true);
 }
 
+/*!
+    \brief Read "shortTitle" dynamic property of the pageId and apply it as the title
+    of corresponding progress item
+*/
+
 void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId)
 {
     if (pageId < 0)
@@ -620,11 +694,21 @@ void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pag
       item->setTitle(shortTitle);
 }
 
+/*!
+    \brief Overwrite to perform steps to be done after files are actually created.
+
+    The default implementation opens editors with the newly generated files.
+*/
+
 bool BaseFileWizard::postGenerateFiles(const QWizard *, const GeneratedFiles &l, QString *errorMessage)
 {
     return BaseFileWizard::postGenerateOpenEditors(l, errorMessage);
 }
 
+/*!
+    \brief Utility to open the editors for the files whose attribute is set accordingly.
+*/
+
 bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage)
 {
     Core::EditorManager *em = Core::EditorManager::instance();
@@ -640,6 +724,11 @@ bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *e
     return true;
 }
 
+/*!
+    \brief Utility that performs an overwrite check on a set of files. It checks if
+    the file exists, can be overwritten at all and prompts the user with a summary.
+*/
+
 BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(const QStringList &files,
                                                                 QString *errorMessage) const
 {
@@ -707,6 +796,10 @@ BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(const QStringLis
     return yes ? OverwriteOk :  OverwriteCanceled;
 }
 
+/*!
+    \brief Build a file name, adding the extension unless baseName already has one.
+*/
+
 QString BaseFileWizard::buildFileName(const QString &path,
                                       const QString &baseName,
                                       const QString &extension)
@@ -727,6 +820,10 @@ QString BaseFileWizard::buildFileName(const QString &path,
     return rc;
 }
 
+/*!
+    \brief Utility that returns the preferred suffix for a mime type
+*/
+
 QString BaseFileWizard::preferredSuffix(const QString &mimeType)
 {
     const QString rc = Core::ICore::instance()->mimeDatabase()->preferredSuffixByType(mimeType);
@@ -736,7 +833,23 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType)
     return rc;
 }
 
-// ------------- StandardFileWizard
+/*!
+    \class Core::StandardFileWizard
+    \brief Convenience class for creating one file.
+
+    It uses Utils::FileWizardDialog and introduces a new virtual to generate the
+    files from path and name.
+
+    \sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::BaseFileWizard
+    \sa Core::Internal::WizardEventLoop
+*/
+
+/*!
+    \fn Core::GeneratedFiles Core::StandardFileWizard::generateFilesFromPath(const QString &path,
+                                                                             const QString &name,
+                                                                             QString *errorMessage) const = 0
+    \brief Newly introduced virtual that creates the files under the path.
+*/
 
 StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameters,
                                        QObject *parent) :
@@ -744,6 +857,10 @@ StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameter
 {
 }
 
+/*!
+    \brief Implemented to create a Utils::FileWizardDialog.
+*/
+
 QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
                                                 const QString &defaultPath,
                                                 const WizardPageList &extensionPages) const
@@ -757,6 +874,10 @@ QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
     return standardWizardDialog;
 }
 
+/*!
+    \brief Implemented to retrieve path and name and call generateFilesFromPath()
+*/
+
 GeneratedFiles StandardFileWizard::generateFiles(const QWizard *w,
                                                  QString *errorMessage) const
 {

src/plugins/coreplugin/basefilewizard.h

@@ -61,11 +61,6 @@ class BaseFileWizardParameterData;
 struct BaseFileWizardPrivate;
 class GeneratedFilePrivate;
 
-/*!
- * Represents a file generated by a wizard. The Wizard class will check for
- * each file whether it already exists and will report any errors that may
- * occur during creation of the files.
- */
 class CORE_EXPORT GeneratedFile
 {
 public:
@@ -115,9 +110,6 @@ private:
 
 typedef QList<GeneratedFile> GeneratedFiles;
 
-/* Parameter class for passing parameters to instances of class Wizard
- * containing name, icon and such. */
-
 class CORE_EXPORT BaseFileWizardParameters
 {
 public:
@@ -155,18 +147,6 @@ private:
 
 CORE_EXPORT QDebug operator<<(QDebug d, const BaseFileWizardParameters &);
 
-/* A generic wizard for creating files.
- *
- * The abstract methods:
- *
- * createWizardDialog() : Called to create the QWizard dialog to be shown
- * generateFiles()      : Generate file content
- *
- * must be implemented. The behaviour can be further customized by overwriting
- * the virtual method:
- * postGenerateFiles()  :   Called after generating the files.
- */
-
 class CORE_EXPORT BaseFileWizard : public IWizard
 {
     Q_DISABLE_COPY(BaseFileWizard)
@@ -187,13 +167,8 @@ public:
 
     virtual void runWizard(const QString &path, QWidget *parent);
 
-    // Build a file name, adding the extension unless baseName already has one
     static QString buildFileName(const QString &path, const QString &baseName, const QString &extension);
-
-    // Sets some standard options on a QWizard
     static void setupWizard(QWizard *);
-
-    // Read "shortTitle" dynamic property of the pageId and apply it as the title of corresponding progress item
     static void applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId);
 
 protected:
@@ -201,44 +176,27 @@ protected:
 
     explicit BaseFileWizard(const BaseFileWizardParameters &parameters, QObject *parent = 0);
 
-    // Overwrite to create the wizard dialog on the parent, adding
-    // the extension pages.
     virtual QWizard *createWizardDialog(QWidget *parent,
                                         const QString &defaultPath,
                                         const WizardPageList &extensionPages) const = 0;
-
-    // Overwrite to query the parameters from the dialog and generate the files.
     virtual GeneratedFiles generateFiles(const QWizard *w,
                                          QString *errorMessage) const = 0;
 
-    /* Physically write files. Re-implement (calling the base implementation)
-     * to create files with CustomGeneratorAttribute set. */
     virtual bool writeFiles(const GeneratedFiles &files, QString *errorMessage);
 
-    /* Overwrite to perform steps to be done after files are actually created.
-     * The default implementation opens editors with the newly generated files. */
     virtual bool postGenerateFiles(const QWizard *w, const GeneratedFiles &l, QString *errorMessage);
 
-    // Utility that returns the preferred suffix for a mime type
     static QString preferredSuffix(const QString &mimeType);
 
-    // Utility that performs an overwrite check on a set of files. It checks if
-    // the file exists, can be overwritten at all and prompts the user.
     enum OverwriteResult { OverwriteOk,  OverwriteError,  OverwriteCanceled };
     OverwriteResult promptOverwrite(const QStringList &files,
                                     QString *errorMessage) const;
-
-    // Utility to open the editors for the files whose attribute is set accordingly.
     static bool postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage = 0);
 
 private:
     BaseFileWizardPrivate *m_d;
 };
 
-// StandardFileWizard convenience class for creating one file. It uses
-// Utils::FileWizardDialog and introduces a new virtual to generate the
-// files from path and name.
-
 class CORE_EXPORT StandardFileWizard : public BaseFileWizard
 {
     Q_DISABLE_COPY(StandardFileWizard)
@@ -246,18 +204,11 @@ class CORE_EXPORT StandardFileWizard : public BaseFileWizard
 
 protected:
     explicit StandardFileWizard(const BaseFileWizardParameters &parameters, QObject *parent = 0);
-
-    // Implemented to create a Utils::FileWizardDialog
     virtual QWizard *createWizardDialog(QWidget *parent,
                                         const QString &defaultPath,
                                         const WizardPageList &extensionPages) const;
-    // Implemented to retrieve path and name and call generateFilesFromPath()
+    virtual GeneratedFiles generateFiles(const QWizard *w, QString *errorMessage) const;
-    virtual GeneratedFiles generateFiles(const QWizard *w,
+    virtual GeneratedFiles generateFilesFromPath(const QString &path, const QString &name,
-                                         QString *errorMessage) const;
-
-    // Newly introduced virtual that creates a file from a path
-    virtual GeneratedFiles generateFilesFromPath(const QString &path,
-                                                 const QString &name,
                                                  QString *errorMessage) const = 0;
 };