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>

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.

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.

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.

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).

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)

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,

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

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.

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.
 */
 
 /*!

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
+    \brief The FeatureSet class is a set of available or required feature sets.
 
-    Features is used to describe available or
-    required feature sets and behaves similar to QFlags.
-
-    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

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.

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

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

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

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
 

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

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.