Doc: use standard wording in \brief commands

QDoc does some magic with the \class and \namespaces
and \brief commands, so the following wording must be used:
"The xxx class yyy ..."

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

17 files changed, 64 insertions, 46 deletions

diff --git a/src/plugins/coreplugin/actionmanager/actionmanager.cpp b/src/plugins/coreplugin/actionmanager/actionmanager.cpp
index b9d11a1f56..d4ed4f7840 100644
--- a/src/plugins/coreplugin/actionmanager/actionmanager.cpp
+++ b/src/plugins/coreplugin/actionmanager/actionmanager.cpp
@@ -55,7 +55,7 @@ using namespace Core::Internal;
     \class Core::ActionManager
     \mainclass
 
-    \brief The action manager is responsible for registration of menus and
+    \brief The ActionManager class is responsible for registration of menus and
     menu items and keyboard shortcuts.
 
     The ActionManager is the central bookkeeper of actions and their shortcuts and layout.
diff --git a/src/plugins/coreplugin/actionmanager/commandbutton.cpp b/src/plugins/coreplugin/actionmanager/commandbutton.cpp
index 7176751112..7f5917aa8b 100644
--- a/src/plugins/coreplugin/actionmanager/commandbutton.cpp
+++ b/src/plugins/coreplugin/actionmanager/commandbutton.cpp
@@ -37,7 +37,8 @@ using namespace Core;
 /*!
     \class Core::CommandButton
 
-    \brief A tool button associated with one of registered Command objects.
+    \brief The CommandButton class is a tool button associated with one of
+    the registered Command objects.
 
     Tooltip of this button consists of toolTipBase property value and Command's
     key sequence which is automatically updated when user changes it.
diff --git a/src/plugins/coreplugin/basefilewizard.cpp b/src/plugins/coreplugin/basefilewizard.cpp
index d0c9d91718..74d49cef36 100644
--- a/src/plugins/coreplugin/basefilewizard.cpp
+++ b/src/plugins/coreplugin/basefilewizard.cpp
@@ -100,8 +100,9 @@ void BaseFileWizardParameterData::clear()
 
 /*!
     \class Core::BaseFileWizardParameters
-    \brief Parameter class for passing parameters to instances of class Wizard
-     containing name, icon and such.
+    \brief The BaseFileWizardParameters class is a parameter class for
+    passing parameters to instances of the class Wizard containing name, icon,
+    and so on.
 
     \sa Core::GeneratedFile, Core::BaseFileWizard, Core::StandardFileWizard
     \sa Core::Internal::WizardEventLoop
@@ -341,7 +342,8 @@ void WizardEventLoop::rejected()
 
 /*!
     \class Core::BaseFileWizard
-    \brief A generic wizard for creating files.
+    \brief The BaseFileWizard class implements a generic wizard for
+    creating files.
 
     The abstract methods:
     \list
@@ -781,7 +783,8 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType)
 
 /*!
     \class Core::StandardFileWizard
-    \brief Convenience class for creating one file.
+    \brief The StandardFileWizard class is a convenience class for
+    creating one file.
 
     It uses Utils::FileWizardDialog and introduces a new virtual to generate the
     files from path and name.
diff --git a/src/plugins/coreplugin/dialogs/ioptionspage.cpp b/src/plugins/coreplugin/dialogs/ioptionspage.cpp
index db3b8006ca..34f1de78a2 100644
--- a/src/plugins/coreplugin/dialogs/ioptionspage.cpp
+++ b/src/plugins/coreplugin/dialogs/ioptionspage.cpp
@@ -32,7 +32,8 @@
 /*!
   \class Core::IOptionsPage
   \mainclass
-  \brief The IOptionsPage is an interface for providing options pages.
+  \brief The IOptionsPage class is an interface for providing pages for the
+  \gui Options dialog (called \gui Preferences on Mac OS).
 
   You need to subclass this interface and put an instance of your subclass
   into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject).
diff --git a/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp b/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp
index 9ec8fd9f3d..bdde354b96 100644
--- a/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp
+++ b/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp
@@ -44,9 +44,11 @@ enum { FileNameRole = Qt::UserRole + 1 };
 
 /*!
     \class Core::Internal::PromptOverwriteDialog
-    \brief Prompts the user to overwrite a list of files, which he can check.
+    \brief The PromptOverwriteDialog class implements a dialog that asks
+    users whether they want to overwrite files.
 
-    Displays the common folder and the files in a checkable list.
+    The dialog displays the common folder and the files in a list where users
+    can select the files to overwrite.
 */
 
 static inline QString fileNameOfItem(const QStandardItem *item)
diff --git a/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp b/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp
index 66d86e973a..18d1e0f10f 100644
--- a/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp
+++ b/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp
@@ -106,7 +106,8 @@ ReadOnlyFilesDialogPrivate::~ReadOnlyFilesDialogPrivate()
 
 /*!
  * \class ReadOnlyFilesDialog
- * \brief Dialog to show a set of files which are classified as not writable.
+ * \brief The ReadOnlyFilesDialog class implements a dialog to show a set of
+ * files that are classified as not writable.
  *
  * Automatically checks which operations are allowed to make the file writable. These operations
  * are Make Writable which tries to set the file permissions in the file system,
diff --git a/src/plugins/coreplugin/documentmanager.cpp b/src/plugins/coreplugin/documentmanager.cpp
index 540e2fa7d2..b39861600c 100644
--- a/src/plugins/coreplugin/documentmanager.cpp
+++ b/src/plugins/coreplugin/documentmanager.cpp
@@ -64,7 +64,7 @@
   \class Core::DocumentManager
   \mainclass
   \inheaderfile documentmanager.h
-  \brief Manages a set of IDocument objects.
+  \brief The DocumentManager class manages a set of IDocument objects.
 
   The DocumentManager service monitors a set of IDocument's. Plugins should register
   files they work with at the service. The files the IDocument's point to will be
diff --git a/src/plugins/coreplugin/editormanager/ieditor.cpp b/src/plugins/coreplugin/editormanager/ieditor.cpp
index d9ad75fe8e..45ed5897df 100644
--- a/src/plugins/coreplugin/editormanager/ieditor.cpp
+++ b/src/plugins/coreplugin/editormanager/ieditor.cpp
@@ -31,7 +31,8 @@
 
 /*!
   \class Core::IEditor
-  \brief The IEditor is an interface for providing different editors for different file types.
+  \brief The IEditor class is an interface for providing different editors for
+  different file types.
 
   Classes that implement this interface are for example the editors for
   C++ files, ui-files and resource files.
diff --git a/src/plugins/coreplugin/editormanager/iexternaleditor.cpp b/src/plugins/coreplugin/editormanager/iexternaleditor.cpp
index c1bd9ceeb3..3813c2d3e7 100644
--- a/src/plugins/coreplugin/editormanager/iexternaleditor.cpp
+++ b/src/plugins/coreplugin/editormanager/iexternaleditor.cpp
@@ -33,8 +33,8 @@
     \class Core::IExternalEditor
     \mainclass
 
-    \brief Core::IExternalEditor allows for registering an external
-    Editor in the \gui{Open With...} dialogs .
+    \brief The IExternalEditor class enables registering an external
+    editor in the \gui{Open with} dialog.
 */
 
 /*!
diff --git a/src/plugins/coreplugin/featureprovider.cpp b/src/plugins/coreplugin/featureprovider.cpp
index f0b1bde4f5..d2dd7ffb39 100644
--- a/src/plugins/coreplugin/featureprovider.cpp
+++ b/src/plugins/coreplugin/featureprovider.cpp
@@ -33,7 +33,8 @@
     \class Core::IFeatureProvider
     \mainclass
 
-    \brief The class IFeatureProvider defines an interface to manage features for wizards
+    \brief The IFeatureProvider class defines an interface to manage features
+    for wizards.
 
     The features provided by an object in the object pool implementing IFeatureProvider
     will be respected by wizards implementing IWizard.
@@ -68,10 +69,8 @@
 /*!
     \class Core::Feature
 
-    \brief This class describes a single Feature
-
-    This class describes a single Feature to be used
-    in Core::FeatureProvider::Features.
+    \brief The Feature class describes a single feature to be used in
+    Core::FeatureProvider::Features.
 
     \sa Core::FeaturesSet
     \sa Core::IWizard
@@ -81,12 +80,10 @@
 /*!
     \class Core::FeatureSet
 
-    \brief This class is a set of features
-
-    Features is used to describe available or
-    required feature sets and behaves similar to QFlags.
+    \brief The FeatureSet class is a set of available or required feature sets.
 
-    But instead of enums Features relies on string ids
+    This class behaves similarly to QFlags. However, instead of enums, Features
+    relies on string ids
     and is therefore extendable.
 
     \sa Core::Feature
diff --git a/src/plugins/coreplugin/generatedfile.cpp b/src/plugins/coreplugin/generatedfile.cpp
index 3f91be3f1c..c0616efe79 100644
--- a/src/plugins/coreplugin/generatedfile.cpp
+++ b/src/plugins/coreplugin/generatedfile.cpp
@@ -40,7 +40,7 @@ namespace Core {
 
 /*!
     \class Core::GeneratedFile
-    \brief Represents a file generated by a wizard.
+    \brief The GeneratedFile class 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.
diff --git a/src/plugins/coreplugin/icore.cpp b/src/plugins/coreplugin/icore.cpp
index 2a616b592e..a037646c98 100644
--- a/src/plugins/coreplugin/icore.cpp
+++ b/src/plugins/coreplugin/icore.cpp
@@ -47,8 +47,8 @@
 
 /*!
     \class Core::ICore
-    \brief The ICore class allows access to the different part that make up
-    the basic functionality of Qt Creator.
+    \brief The ICore class allows access to the different parts that make up
+    the basic functionality of \QC.
 
     You should never create a subclass of this interface. The one and only
     instance is created by the Core plugin. You can access this instance
diff --git a/src/plugins/coreplugin/icorelistener.h b/src/plugins/coreplugin/icorelistener.h
index fa918c7a2e..9d29802dc6 100644
--- a/src/plugins/coreplugin/icorelistener.h
+++ b/src/plugins/coreplugin/icorelistener.h
@@ -38,8 +38,8 @@ class IEditor;
 /*!
   \class Core::ICoreListener
 
-  \brief Provides a hook for plugins to veto on certain events emitted from
-the core plugin.
+  \brief The ICoreListener class provides a hook for plugins to veto on certain
+  events emitted from the core plugin.
 
   You implement this interface if you want to prevent certain events from
   occurring, e.g.  if you want to prevent the closing of the whole application
diff --git a/src/plugins/coreplugin/id.cpp b/src/plugins/coreplugin/id.cpp
index 20a5e21837..8454b427f1 100644
--- a/src/plugins/coreplugin/id.cpp
+++ b/src/plugins/coreplugin/id.cpp
@@ -43,8 +43,8 @@ namespace Core {
 /*!
     \class Core::Id
 
-    \brief The class Id encapsulates an identifier that is unique
-    within a specific running Qt Creator process.
+    \brief The Id class encapsulates an identifier that is unique
+    within a specific running \QC process.
 
     \c{Core::Id} is used as facility to identify objects of interest
     in a more typesafe and faster manner than a plain \c QString or
diff --git a/src/plugins/coreplugin/mimedatabase.cpp b/src/plugins/coreplugin/mimedatabase.cpp
index f8c66a5b24..3d84dbd113 100644
--- a/src/plugins/coreplugin/mimedatabase.cpp
+++ b/src/plugins/coreplugin/mimedatabase.cpp
@@ -93,7 +93,8 @@ enum {
 /*!
     \class Core::IMagicMatcher
 
-    \brief Interface for a Mime type magic matcher (examinig file contents).
+    \brief The IMagicMatcher class is an interface for a MIME type magic
+    matcher that examines file contents to determine the MIME type of a file.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -109,7 +110,8 @@ namespace Internal {
 /*!
     \class Core::Internal::FileMatchContext
 
-    \brief Context passed on to the mime types when looking for a file match.
+    \brief The FileMatchContext class is the context passed on to the MIME
+    types when looking for a file match.
 
     It exists to enable reading the file contents "on demand"
     (as opposed to each mime type trying to open and read while checking).
@@ -173,7 +175,8 @@ QByteArray FileMatchContext::data()
 
 /*!
     \class Core::Internal::BinaryMatcher
-    \brief The binary fallback matcher for mime type "application/octet-stream".
+    \brief The BinaryMatcher class is the binary fallback matcher for the MIME
+    type \c{application/octet-stream}.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::HeuristicTextMagicMatcher
@@ -190,7 +193,8 @@ public:
 
 /*!
     \class Core::Internal::HeuristicTextMagicMatcher
-    \brief Heuristic text file matcher for mime types.
+    \brief The HeuristicTextMagicMatcher class implements a heuristic text file
+    matcher for MIME types.
 
     If the data do not contain any character below tab (9), detect as text.
     Additionally, check on UTF16 byte order markers.
@@ -235,7 +239,8 @@ bool HeuristicTextMagicMatcher::matches(const QByteArray &data) const
 
 /*!
     \class Core::MagicRule
-    \brief Base class for standard Magic match rules based on contents
+    \brief The MagicRule class is a base class for standard Magic matching rules
+    based on contents
     and offset specification.
 
     Stores the offset and provides conversion helpers.
@@ -281,7 +286,7 @@ QPair<int, int> MagicRule::fromOffset(const QString &offset)
 
 /*!
     \class Core::MagicStringRule
-    \brief Match on a string.
+    \brief The MagicStringRule class provides rules for matching strings.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -327,7 +332,8 @@ bool MagicStringRule::matches(const QByteArray &data) const
 
 /*!
     \class Core::MagicByteRule
-    \brief Match on a sequence of binary data.
+    \brief The MagicByteRule class provides rules for matching a sequence of
+    binary data.
 
     Format:
     \code
@@ -410,7 +416,8 @@ bool MagicByteRule::matches(const QByteArray &data) const
 /*!
     \class Core::MagicRuleMatcher
 
-    \brief A Magic matcher that checks a number of rules based on operator "or".
+    \brief The MagicRuleMatcher class implements a Magic matcher that checks the
+    number of rules based on the boolean operator OR.
 
     It is used for rules parsed from XML files.
 
@@ -474,7 +481,8 @@ IMagicMatcher::IMagicMatcherList MagicRuleMatcher::createMatchers(
 
 /*!
     \class Core::GlobPattern
-    \brief Glob pattern for file names for mime type matching.
+    \brief The GlobPattern class provides a glob pattern for file names for
+    MIME type matching.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -518,7 +526,7 @@ bool MimeGlobPattern::matches(const QString &fileName) const
 /*!
     \class Core::MimeType
 
-    \brief Mime type data used in Qt Creator.
+    \brief The MimeType class contains MIME type data used in \QC.
 
     Contains most information from standard mime type XML database files.
 
@@ -918,7 +926,8 @@ namespace Internal {
 
 /*!
     \class Core::Internal::BaseMimeTypeParser
-    \brief Generic parser for a sequence of <mime-type>.
+    \brief The BaseMimeTypeParser class provides a generic parser for a
+    sequence of <mime-type>.
 
     Calls abstract handler function process for MimeType it finds.
 
@@ -1183,7 +1192,8 @@ MimeMapEntry::MimeMapEntry(const MimeType &t, int aLevel) :
 
 /*!
     \class Core::MimeDatabase
-    \brief Mime data base to which the plugins can add the mime types they handle.
+    \brief The MimeDatabase class is a MIME type database to which the plugins
+    can add the MIME types they handle.
 
     The class is protected by a QMutex and can therefore be accessed by threads.
 
@@ -1302,7 +1312,7 @@ MimeDatabasePrivate::MimeDatabasePrivate() :
 
 /*!
     \class Core::Internal::MimeTypeParser
-    \brief Mime type parser
+    \brief The MimeTypeParser class provides a MIME type parser.
 
     Populates Core::MimeDataBase
 
diff --git a/src/plugins/coreplugin/settingsdatabase.cpp b/src/plugins/coreplugin/settingsdatabase.cpp
index ccfaae9b94..c2ca076783 100644
--- a/src/plugins/coreplugin/settingsdatabase.cpp
+++ b/src/plugins/coreplugin/settingsdatabase.cpp
@@ -42,7 +42,8 @@
 
 /*!
     \class Core::SettingsDatabase
-    \brief An alternative to the application-wide QSettings that is more
+    \brief The SettingsDatabase class offers an alternative to the
+    application-wide QSettings that is more
     suitable for storing large amounts of data.
 
     The settings database is SQLite based, and lazily retrieves data when it
diff --git a/src/plugins/coreplugin/textdocument.cpp b/src/plugins/coreplugin/textdocument.cpp
index f44a86f2b7..c083cf2eb2 100644
--- a/src/plugins/coreplugin/textdocument.cpp
+++ b/src/plugins/coreplugin/textdocument.cpp
@@ -35,7 +35,8 @@
 
 /*!
     \class Core::TextFile
-    \brief Base class for text files with encoding helpers.
+    \brief The TextFile class is a base class for text files with encoding
+    helpers.
 
     Stores the format obtained from read operations and uses that when writing
     out files, thus ensuring that CRLF/encodings are preserved.