Doc: edit coreplugin docs

Remove \brief commands for functions.
Use standard wording for QDoc commands.
Fix style and grammar issues.
Use the \a command instead of the \c command for attributes
in function descriptions.
Do not use \returns, because it does not exist.

Change-Id: Icd32b519670cb376e246bab3a58fe7e98d2529ea
Reviewed-by: Eike Ziller <eike.ziller@digia.com>

1 files changed, 27 insertions, 24 deletions

diff --git a/src/plugins/coreplugin/basefilewizard.cpp b/src/plugins/coreplugin/basefilewizard.cpp
index 74d49cef36..1a6f6a9756 100644
--- a/src/plugins/coreplugin/basefilewizard.cpp
+++ b/src/plugins/coreplugin/basefilewizard.cpp
@@ -248,9 +248,10 @@ void BaseFileWizardParameters::setDescriptionImage(const QString &path)
 
 /*!
     \class Core::Internal::WizardEventLoop
-    \brief Special event loop that runs a QWizard and terminates if the page changes.
+    \brief The WizardEventLoop class implements a 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
+    Used 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:
@@ -345,13 +346,12 @@ void WizardEventLoop::rejected()
     \brief The BaseFileWizard class implements a generic wizard for
     creating files.
 
-    The abstract methods:
+    The following abstract methods must be implemented:
     \list
-    \li createWizardDialog(): Called to create the QWizard dialog to be shown
-    \li generateFiles(): Generate file content
+    \li createWizardDialog(): Called to create the QWizard dialog to be shown.
+    \li generateFiles(): Generates 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.
 
@@ -561,21 +561,23 @@ Core::IWizard::WizardFlags BaseFileWizard::flags() const
 
 /*!
     \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.
+                                                                  const WizardDialogParameters &wizardDialogParameters) const
+
+    Creates the wizard dialog on the \a parent with the
+    \a wizardDialogParameters.
 */
 
 /*!
     \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.
+    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.
+    \note This does not generate physical files, but merely the list of
+    Core::GeneratedFile.
 */
 
 /*!
-    \brief Physically write files.
+    Physically writes files.
 
     Re-implement (calling the base implementation) to create files with CustomGeneratorAttribute set.
 */
@@ -592,7 +594,7 @@ bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessa
 }
 
 /*!
-    \brief Sets some standard options on a QWizard
+    Sets some standard options on a QWizard.
 */
 
 void BaseFileWizard::setupWizard(QWizard *w)
@@ -614,8 +616,8 @@ void BaseFileWizard::setupWizard(QWizard *w)
 }
 
 /*!
-    \brief Read "shortTitle" dynamic property of the pageId and apply it as the title
-    of corresponding progress item
+    Reads the \c shortTitle dynamic property of \a pageId and applies it as
+    the title of corresponding progress item.
 */
 
 void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId)
@@ -634,7 +636,7 @@ void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pag
 }
 
 /*!
-    \brief Overwrite to perform steps to be done after files are actually created.
+    Overwrite to perform steps to be done after files are actually created.
 
     The default implementation opens editors with the newly generated files.
 */
@@ -645,7 +647,7 @@ bool BaseFileWizard::postGenerateFiles(const QWizard *, const GeneratedFiles &l,
 }
 
 /*!
-    \brief Utility to open the editors for the files whose attribute is set accordingly.
+    Opens the editors for the files whose attribute is set accordingly.
 */
 
 bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage)
@@ -663,8 +665,8 @@ bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *e
 }
 
 /*!
-    \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.
+    Performs an overwrite check on a set of \a files. Checks if the file exists and
+    can be overwritten at all, and then prompts the user with a summary.
 */
 
 BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles *files,
@@ -745,7 +747,8 @@ BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles *
 }
 
 /*!
-    \brief Build a file name, adding the extension unless baseName already has one.
+    Constructs a file name, adding the \a extension unless \a baseName already has
+    one.
 */
 
 QString BaseFileWizard::buildFileName(const QString &path,
@@ -769,7 +772,7 @@ QString BaseFileWizard::buildFileName(const QString &path,
 }
 
 /*!
-    \brief Utility that returns the preferred suffix for a mime type
+    Returns the preferred suffix for \a mimeType.
 */
 
 QString BaseFileWizard::preferredSuffix(const QString &mimeType)
@@ -797,7 +800,7 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType)
     \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.
+    Creates the files with the \a name under the \a path.
 */
 
 StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameters,
@@ -807,7 +810,7 @@ StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameter
 }
 
 /*!
-    \brief Implemented to create a Utils::FileWizardDialog.
+    Creates a Utils::FileWizardDialog.
 */
 
 QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
@@ -825,7 +828,7 @@ QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
 }
 
 /*!
-    \brief Implemented to retrieve path and name and call generateFilesFromPath()
+    Retrieves \a path and \a fileName and calls \c generateFilesFromPath().
 */
 
 GeneratedFiles StandardFileWizard::generateFiles(const QWizard *w,