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>

src/plugins/coreplugin/actionmanager/actionmanager.cpp

@@ -169,7 +169,7 @@ ActionManager *ActionManager::instance()
 }
 
 /*!
-    \brief Creates a new menu with the given \a id.
+    Creates a new menu with the given \a id.
 
     Returns a new ActionContainer that you can use to get the QMenu instance
     or to add menu items to the menu. The ActionManager owns
@@ -196,7 +196,7 @@ ActionContainer *ActionManager::createMenu(Id id)
 }
 
 /*!
-    \brief Creates a new menu bar with the given \a id.
+    Creates a new menu bar with the given \a id.
 
     Returns a new ActionContainer that you can use to get the QMenuBar instance
     or to add menus to the menu bar. The ActionManager owns
@@ -221,7 +221,7 @@ ActionContainer *ActionManager::createMenuBar(Id id)
 }
 
 /*!
-    \brief Makes an \a action known to the system under the specified \a id.
+    Makes an \a action known to the system under the specified \a id.
 
     Returns a command object that represents the action in the application and is
     owned by the ActionManager. You can register several actions with the
@@ -243,7 +243,7 @@ Command *ActionManager::registerAction(QAction *action, Id id, const Context &co
 }
 
 /*!
-    \brief Makes a \a shortcut known to the system under the specified \a id.
+    Makes a \a shortcut known to the system under the specified \a id.
 
     Returns a command object that represents the shortcut in the application and is
     owned by the ActionManager. You can registered several shortcuts with the
@@ -292,7 +292,7 @@ Command *ActionManager::registerShortcut(QShortcut *shortcut, Id id, const Conte
 }
 
 /*!
-    \brief Returns the Command object that is known to the system
+    Returns the Command object that is known to the system
     under the given \a id.
 
     \sa ActionManager::registerAction()
@@ -310,7 +310,7 @@ Command *ActionManager::command(Id id)
 }
 
 /*!
-    \brief Returns the IActionContainter object that is know to the system
+    Returns the IActionContainter object that is know to the system
     under the given \a id.
 
     \sa ActionManager::createMenu()
@@ -329,7 +329,7 @@ ActionContainer *ActionManager::actionContainer(Id id)
 }
 
 /*!
- * \brief Returns all commands that have been registered.
+ * Returns all commands that have been registered.
  */
 QList<Command *> ActionManager::commands()
 {
@@ -341,7 +341,7 @@ QList<Command *> ActionManager::commands()
 }
 
 /*!
-    \brief Removes the knowledge about an \a action under the specified \a id.
+    Removes the knowledge about an \a action under the specified \a id.
 
     Usually you do not need to unregister actions. The only valid use case for unregistering
     actions, is for actions that represent user definable actions, like for the custom Locator
@@ -372,7 +372,7 @@ void ActionManager::unregisterAction(QAction *action, Id id)
 }
 
 /*!
-    \brief Removes the knowledge about a shortcut under the specified \a id.
+    Removes the knowledge about a shortcut under the specified \a id.
 
     Usually you do not need to unregister shortcuts. The only valid use case for unregistering
     shortcuts, is for shortcuts that represent user definable actions. If the user removes such an action,

src/plugins/coreplugin/actionmanager/command.cpp

@@ -44,13 +44,13 @@
     \class Core::Command
     \mainclass
 
-    \brief The class Command represents an action like a menu item, tool button, or shortcut.
+    \brief The Command class represents an action, such as a menu item, tool button, or shortcut.
-    You don't create Command objects directly, instead use \l{ActionManager::registerAction()}
+    You do not create Command objects directly, but use \l{ActionManager::registerAction()}
     to register an action and retrieve a Command. The Command object represents the user visible
     action and its properties. If multiple actions are registered with the same ID (but
     different contexts) the returned Command is the shared one between these actions.
 
-    A Command has two basic properties: A default shortcut and a default text. The default
+    A Command has two basic properties: a default shortcut and a default text. The default
     shortcut is a key sequence that the user can use to trigger the active action that
     the Command represents. The default text is e.g. used for representing the Command
     in the keyboard shortcut preference pane. If the default text is empty, the text
@@ -68,7 +68,7 @@
 
 /*!
     \enum Command::CommandAttribute
-    Defines how the user visible action is updated when the active action changes.
+    This enum defines how the user visible action is updated when the active action changes.
     The default is to update the enabled and visible state, and to disable the
     user visible action when there is no active action.
     \omitvalue CA_Mask
@@ -86,7 +86,7 @@
 
 /*!
     \fn void Command::setDefaultKeySequence(const QKeySequence &key)
-    Set the default keyboard shortcut that can be used to activate this command to \a key.
+    Sets the default keyboard shortcut that can be used to activate this command to \a key.
     This is used if the user didn't customize the shortcut, or resets the shortcut
     to the default one.
 */
@@ -116,10 +116,10 @@
 
 /*!
     \fn void Command::setDescription(const QString &text)
-    Set the \a text that is used to represent the Command in the
+    Sets the \a text that is used to represent the Command in the
-    keyboard shortcut settings dialog. If you don't set this,
+    keyboard shortcut settings dialog. If you do not set this,
     the current text from the user visible action is taken (which
-    is ok in many cases).
+    is fine in many cases).
 */
 
 /*!
@@ -160,7 +160,7 @@
 
 /*!
     \fn void Command::setAttribute(CommandAttribute attribute)
-    Add the \a attribute to the attributes of this Command.
+    Adds \a attribute to the attributes of this Command.
     \sa CommandAttribute
     \sa removeAttribute()
     \sa hasAttribute()
@@ -168,14 +168,14 @@
 
 /*!
     \fn void Command::removeAttribute(CommandAttribute attribute)
-    Remove the \a attribute from the attributes of this Command.
+    Removes \a attribute from the attributes of this Command.
     \sa CommandAttribute
     \sa setAttribute()
 */
 
 /*!
     \fn bool Command::hasAttribute(CommandAttribute attribute) const
-    Returns if the Command has the \a attribute set.
+    Returns whether the Command has the \a attribute set.
     \sa CommandAttribute
     \sa removeAttribute()
     \sa setAttribute()
@@ -183,19 +183,19 @@
 
 /*!
     \fn bool Command::isActive() const
-    Returns if the Command has an active action/shortcut for the current
+    Returns whether the Command has an active action or shortcut for the current
     context.
 */
 
 /*!
     \fn bool Command::isScriptable() const
-    Returns if the Command is scriptable. A scriptable command can be called
+    Returns whether the Command is scriptable. A scriptable command can be called
     from a script without the need for the user to interact with it.
 */
 
 /*!
     \fn bool Command::isScriptable(const Context &) const
-    Returns if the Command is scriptable for the given context.
+    Returns whether the Command is scriptable for the given context.
     A scriptable command can be called from a script without the need for the user to
     interact with it.
 */

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 createWizardDialog(): Called to create the QWizard dialog to be shown.
-    \li generateFiles(): Generate file content
+    \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 WizardDialogParameters &wizardDialogParameters) const
-                                                                  const WizardPageList &extensionPages) const = 0
+
-    \brief Implement to create the wizard dialog on the parent, adding the extension pages.
+    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
+    Reads the \c shortTitle dynamic property of \a pageId and applies it as
-    of corresponding progress item
+    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
+    Performs an overwrite check on a set of \a files. Checks if the file exists and
-    the file exists, can be overwritten at all and prompts the user with a summary.
+    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,

src/plugins/coreplugin/dialogs/ioptionspage.cpp

@@ -39,15 +39,16 @@
   into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject).
   Guidelines for implementing:
   \list
-  \li id() is a unique identifier for referencing this page
+  \li \c id() is a unique identifier for referencing this page
-  \li displayName() is the (translated) name for display
+  \li \c displayName() is the (translated) name for display
-  \li category() is the unique id for the category that the page should be displayed in
+  \li \c category() is the unique id for the category that the page should be displayed in
-  \li displayCategory() is the translated name of the category
+  \li \c displayCategory() is the translated name of the category
-  \li createPage() is called to retrieve the widget to show in the preferences dialog
+  \li \c createPage() is called to retrieve the widget to show in the
+        \gui Options dialog
      The widget will be destroyed by the widget hierarchy when the dialog closes
-  \li apply() is called to store the settings. It should detect if any changes have been
+  \li \c apply() is called to store the settings. It should detect if any changes have been
          made and store those
-  \li finish() is called directly before the preferences dialog closes
+  \li \c finish() is called directly before the \gui Options dialog closes
-  \li matches() is used for the options dialog search filter
+  \li \c matches() is used for the \gui Options dialog search filter
   \endlist
 */

src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp

@@ -158,7 +158,7 @@ ReadOnlyFilesDialog::~ReadOnlyFilesDialog()
 }
 
 /*!
- * \brief Set a user defined message in the dialog.
+ * Sets a user defined message in the dialog.
  * \internal
  */
 void ReadOnlyFilesDialog::setMessage(const QString &message)
@@ -167,8 +167,8 @@ void ReadOnlyFilesDialog::setMessage(const QString &message)
 }
 
 /*!
- * \brief Enable the error output to the user via a messageBox.
+ * Enables the error output to the user via a message box. \a warning should
- * \param warning Added to the dialog, should show possible consequences if the file is still read only.
+ * show the possible consequences if the file is still read only.
  * \internal
  */
 void ReadOnlyFilesDialog::setShowFailWarning(bool show, const QString &warning)
@@ -178,7 +178,7 @@ void ReadOnlyFilesDialog::setShowFailWarning(bool show, const QString &warning)
 }
 
 /*!
- * \brief Opens a message box with an error description according to the type.
+ * Opens a message box with an error description according to the type.
  * \internal
  */
 void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyResult type) const
@@ -237,12 +237,13 @@ void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyRe
 }
 
 /*!
- * \brief Executes the dialog.
+ * Executes the ReadOnlyFilesDialog dialog.
- * \return ReadOnlyResult which gives information about the operation which was used to make the files writable.
+ * Returns ReadOnlyResult to provide information about the operation that was
+ * used to make the files writable.
  * \internal
  *
- * Also displays an error dialog when some operations can't be executed and the function
+ * Also displays an error dialog when some operations cannot be executed and the
- * setShowFailWarning was called.
+ * function \c setShowFailWarning() was called.
  */
 int ReadOnlyFilesDialog::exec()
 {
@@ -287,9 +288,9 @@ int ReadOnlyFilesDialog::exec()
 }
 
 /*!
- * \brief Creates a radio button in the column specified with type.
+ * Creates a radio button in the group \a group and in the column specified by
- * \param group the created button will be added to this group.
+ * \a type.
- * \return the created button.
+ * Returns the created button.
  * \internal
  */
 QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *item, QButtonGroup *group,
@@ -304,7 +305,8 @@ QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *ite
 }
 
 /*!
- * \brief Checks the type of the select all combo box and change the user selection per file accordingly.
+ * Checks the type of the select all combo box and changes the user selection
+ * per file accordingly.
  * \internal
  */
 void ReadOnlyFilesDialog::setAll(int index)
@@ -331,7 +333,8 @@ void ReadOnlyFilesDialog::setAll(int index)
 }
 
 /*!
- * \brief Updates the select all combo box depending on the selection in the tree widget the user made.
+ * Updates the select all combo box depending on the selection the user made in
+ * the tree widget.
  * \internal
  */
 void ReadOnlyFilesDialog::updateSelectAll()
@@ -349,8 +352,10 @@ void ReadOnlyFilesDialog::updateSelectAll()
 }
 
 /*!
- * \brief Adds files to the dialog and check for possible operation to make the file writable.
+ * Adds files to the dialog and checks for a possible operation to make the file
- * \param fileNames A List of files which should be added to the dialog.
+ * writable.
+ * \a fileNames contains the list of the files that should be added to the
+ * dialog.
  * \internal
  */
 void ReadOnlyFilesDialog::initDialog(const QStringList &fileNames)

src/plugins/coreplugin/documentmanager.cpp

@@ -66,27 +66,29 @@
   \inheaderfile documentmanager.h
   \brief The DocumentManager class manages a set of IDocument objects.
 
-  The DocumentManager service monitors a set of IDocument's. Plugins should register
+  The DocumentManager service monitors a set of IDocument objects. Plugins
-  files they work with at the service. The files the IDocument's point to will be
+  should register files they work with at the service. The files the IDocument
-  monitored at filesystem level. If a file changes, the status of the IDocument's
+  objects point to will be monitored at filesystem level. If a file changes,
+  the status of the IDocument object
   will be adjusted accordingly. Furthermore, on application exit the user will
   be asked to save all modified files.
 
   Different IDocument objects in the set can point to the same file in the
-  filesystem. The monitoring for a IDocument can be blocked by blockFileChange(), and
+  filesystem. The monitoring for an IDocument can be blocked by
-  enabled again by unblockFileChange().
+  \c blockFileChange(), and enabled again by \c unblockFileChange().
 
-  The functions expectFileChange() and unexpectFileChange() mark a file change
+  The functions \c expectFileChange() and \c unexpectFileChange() mark a file change
   as expected. On expected file changes all IDocument objects are notified to reload
   themselves.
 
   The DocumentManager service also provides two convenience methods for saving
-  files: saveModifiedFiles() and saveModifiedFilesSilently(). Both take a list
+  files: \c saveModifiedFiles() and \c saveModifiedFilesSilently(). Both take a list
   of FileInterfaces as an argument, and return the list of files which were
   _not_ saved.
 
-  The service also manages the list of recent files to be shown to the user
+  The service also manages the list of recent files to be shown to the user.
-  (see addToRecentFiles() and recentFiles()).
+
+  \sa addToRecentFiles(), recentFiles()
  */
 
 static const char settingsGroupC[] = "RecentFiles";
@@ -156,7 +158,7 @@ struct DocumentManagerPrivate
     QString m_projectsDirectory;
     bool m_useProjectsDirectory;
     QString m_buildDirectory;
-    // When we are callling into a IDocument
+    // When we are calling into an IDocument
     // we don't want to receive a changed()
     // signal
     // That makes the code easier
@@ -359,12 +361,13 @@ static void dump()
 */
 
 /*!
-    \brief Tells the file manager that a file has been renamed on disk from within Qt Creator.
+    Tells the file manager that a file has been renamed on disk from within \QC.
 
-    Needs to be called right after the actual renaming on disk (i.e. before the file system
+    Needs to be called right after the actual renaming on disk (that is, before
+    the file system
     watcher can report the event during the next event loop run). \a from needs to be an absolute file path.
     This will notify all IDocument objects pointing to that file of the rename
-    by calling IDocument::rename, and update the cached time and permission
+    by calling \c IDocument::rename(), and update the cached time and permission
     information to avoid annoying the user with "file has been removed"
     popups.
 */
@@ -402,7 +405,8 @@ void DocumentManager::fileNameChanged(const QString &oldName, const QString &new
 }
 
 /*!
-    Adds a IDocument object to the collection. If \a addWatcher is true (the default),
+    Adds an IDocument object to the collection. If \a addWatcher is \c true
+    (the default),
     the file is added to a file system watcher that notifies the file manager
     about file changes.
 */
@@ -420,9 +424,10 @@ void DocumentManager::documentDestroyed(QObject *obj)
 }
 
 /*!
-    Removes a IDocument object from the collection.
+    Removes an IDocument object from the collection.
 
-    Returns true if the file specified by \a document had the addWatcher argument to addDocument() set.
+    Returns \c true if the file specified by \a document had the \a addWatcher
+    argument to \a addDocument() set.
 */
 bool DocumentManager::removeDocument(IDocument *document)
 {
@@ -481,7 +486,7 @@ QString DocumentManager::fixFileName(const QString &fileName, FixMode fixmode)
 }
 
 /*!
-    Returns the list of IDocument's that have been modified.
+    Returns the list of IDocuments that have been modified.
 */
 QList<IDocument *> DocumentManager::modifiedDocuments()
 {
@@ -501,7 +506,7 @@ QList<IDocument *> DocumentManager::modifiedDocuments()
 }
 
 /*!
-    Any subsequent change to \a fileName is treated as a expected file change.
+    Any subsequent change to \a fileName is treated as an expected file change.
 
     \see DocumentManager::unexpectFileChange(const QString &fileName)
 */
@@ -525,7 +530,7 @@ static void updateExpectedState(const QString &fileName)
 }
 
 /*!
-    Any change to \a fileName are unexpected again.
+    Any changes to \a fileName are unexpected again.
 
     \see DocumentManager::expectFileChange(const QString &fileName)
 */
@@ -550,7 +555,8 @@ void DocumentManager::unexpectFileChange(const QString &fileName)
 /*!
     Tries to save the files listed in \a documents. The \a cancelled argument is set to true
     if the user cancelled the dialog. Returns the files that could not be saved. If the files
-    listed in documents have no write permissions an additional dialog will be prompted to
+    listed in documents have no write permissions, an additional dialog will be
+    displayed to
     query the user for these permissions.
 */
 QList<IDocument *> DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &documents, bool *cancelled)
@@ -559,14 +565,17 @@ QList<IDocument *> DocumentManager::saveModifiedDocumentsSilently(const QList<ID
 }
 
 /*!
-    Asks the user whether to save the files listed in \a documents .
+    Asks the user whether to save the files listed in \a documents. Opens a
-    Opens a dialog with the given \a message, and a additional
+    dialog that displays the \a message, and additional text to ask the users
-    text that should be used to ask if the user wants to enabled automatic save
+    if they want to enable automatic saving
     of modified files (in this context).
-    The \a cancelled argument is set to true if the user cancelled the dialog,
+
-    \a alwaysSave is set to match the selection of the user, if files should
+    The \a cancelled argument is set to true if the user cancels the dialog.
+    \a alwaysSave is set to match the selection of the user if files should
     always automatically be saved. If the files listed in documents have no write
-    permissions an additional dialog will be prompted to query the user for these permissions.
+    permissions, an additional dialog will be displayed to query the user for
+    these permissions.
+
     Returns the files that have not been saved.
 */
 QList<IDocument *> DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents,
@@ -740,7 +749,7 @@ QString DocumentManager::getSaveFileNameWithExtension(const QString &title, cons
 }
 
 /*!
-    Asks the user for a new file name (Save File As) for /arg document.
+    Asks the user for a new file name (\gui {Save File As}) for \a document.
 */
 QString DocumentManager::getSaveAsFileName(const IDocument *document, const QString &filter, QString *selectedFilter)
 {
@@ -775,9 +784,9 @@ QString DocumentManager::getSaveAsFileName(const IDocument *document, const QStr
 
 /*!
     Asks the user for a set of file names to be opened. The \a filters
-    and \a selectedFilter parameters is interpreted like in
+    and \a selectedFilter arguments are interpreted like in
-    QFileDialog::getOpenFileNames(), \a pathIn specifies a path to open the dialog
+    \c QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the
-    in, if that is not overridden by the users policy.
+    dialog in if that is not overridden by the user's policy.
 */
 
 QStringList DocumentManager::getOpenFileNames(const QString &filters,
@@ -1047,8 +1056,8 @@ void DocumentManager::syncWithEditor(const QList<Core::IContext *> &context)
 
 /*!
     Adds the \a fileName to the list of recent files. Associates the file to
-    be reopened with an editor of the given \a editorId, if possible.
+    be reopened with the editor that has the specified \a editorId, if possible.
-    \a editorId defaults to the empty id, which means to let the system figure out
+    \a editorId defaults to the empty id, which lets \QC figure out
     the best editor itself.
 */
 void DocumentManager::addToRecentFiles(const QString &fileName, const Id &editorId)
@@ -1070,7 +1079,7 @@ void DocumentManager::addToRecentFiles(const QString &fileName, const Id &editor
 
 /*!
     Clears the list of recent files. Should only be called by
-    the core plugin when the user chooses to clear it.
+    the core plugin when the user chooses to clear the list.
 */
 void DocumentManager::clearRecentFiles()
 {
@@ -1147,8 +1156,8 @@ void readSettings()
 
 /*!
 
-  The current file is e.g. the file currently opened when an editor is active,
+  The current file is the file currently opened when an editor is active,
-  or the selected file in case a Project Explorer is active ...
+  or the selected file in case a Project Explorer is active.
 
   \sa currentFile
   */
@@ -1161,10 +1170,10 @@ void DocumentManager::setCurrentFile(const QString &filePath)
 }
 
 /*!
-  Returns the absolute path of the current file
+  Returns the absolute path of the current file.
 
-  The current file is e.g. the file currently opened when an editor is active,
+  The current file is the file currently opened when an editor is active,
-  or the selected file in case a Project Explorer is active ...
+  or the selected file in case a Project Explorer is active.
 
   \sa setCurrentFile
   */
@@ -1176,7 +1185,7 @@ QString DocumentManager::currentFile()
 /*!
 
   Returns the initial directory for a new file dialog. If there is
-  a current file, use that, else use last visited directory.
+  a current file, uses that, otherwise uses the last visited directory.
 
   \sa setFileDialogLastVisitedDirectory
 */
@@ -1202,7 +1211,7 @@ QString DocumentManager::projectsDirectory()
 
 /*!
 
-  Set the directory for projects.
+  Sets the directory for projects.
 
   \sa projectsDirectory, useProjectsDirectory
 */
@@ -1234,8 +1243,8 @@ void DocumentManager::setBuildDirectory(const QString &directory)
 
 /*!
 
-  Returns whether the directory for projects is to be
+    Returns whether the directory for projects is to be used or whether the user
-  used or the user wants the current directory.
+    chose to use the current directory.
 
   \sa setProjectsDirectory, setUseProjectsDirectory
 */
@@ -1259,7 +1268,7 @@ void DocumentManager::setUseProjectsDirectory(bool useProjectsDirectory)
 
 /*!
 
-  Returns last visited directory of a file dialog.
+  Returns the last visited directory of a file dialog.
 
   \sa setFileDialogLastVisitedDirectory, fileDialogInitialDirectory
 
@@ -1272,7 +1281,7 @@ QString DocumentManager::fileDialogLastVisitedDirectory()
 
 /*!
 
-  Set the last visited directory of a file dialog that will be remembered
+  Sets the last visited directory of a file dialog that will be remembered
   for the next one.
 
   \sa fileDialogLastVisitedDirectory, fileDialogInitialDirectory

src/plugins/coreplugin/editormanager/ieditor.cpp

@@ -35,7 +35,7 @@
   different file types.
 
   Classes that implement this interface are for example the editors for
-  C++ files, ui-files and resource files.
+  C++ files, UI files and resource files.
 
   Whenever a user wants to edit or create a file, the EditorManager scans all
   EditorFactoryInterfaces for suitable editors. The selected EditorFactory
@@ -43,14 +43,17 @@
 
   Guidelines for implementing:
   \list
-  \li displayName() is used as a user visible description of the document (usually filename w/o path).
+  \li \c displayName() is used as a user visible description of the document
-  \li kind() must be the same value as the kind() of the corresponding EditorFactory.
+      (usually filename w/o path).
-  \li The changed() signal should be emitted when the modified state of the document changes
+  \li \c kind() must be the same value as the \c kind() of the corresponding
-     (so /bold{not} every time the document changes, but /bold{only once}).
+      EditorFactory.
+  \li The \c changed() signal should be emitted when the modified state of the
+      document changes (so \e not every time the document changes, but
+      \e {only once}).
   \li If duplication is supported, you need to ensure that all duplicates
-        return the same file().
+        return the same \c file().
-  \li QString preferredMode() const is the mode the editor manager should activate.
+  \li QString \c preferredMode() const is the mode the editor manager should
-     Some editors use a special mode (such as Design mode).
+      activate. Some editors use a special mode (such as \gui Design mode).
   \endlist
 
   \sa Core::EditorFactoryInterface Core::IContext

src/plugins/coreplugin/editormanager/iexternaleditor.cpp

@@ -56,6 +56,6 @@
 
     \fn bool IExternalEditor::startEditor(const QString &fileName, QString *errorMessage) = 0;
 
-    Opens the editor with \param fileName. Returns true on success or false
+    Opens the editor with \a fileName. Returns \c true on success or \c false
-    on failure along with the error in \param errorMessage.
+    on failure along with the error in \a errorMessage.
 */

src/plugins/coreplugin/featureprovider.cpp

@@ -39,8 +39,10 @@
     The features provided by an object in the object pool implementing IFeatureProvider
     will be respected by wizards implementing IWizard.
 
-    This feature set, provided by all instances of IFeatureProvider in the object pool, is checked against IWizard::requiredFeatures()
+    This feature set, provided by all instances of IFeatureProvider in the
-    and only if all required features are available the wizard is displayed when creating a new file or project.
+    object pool, is checked against \c IWizard::requiredFeatures()
+    and only if all required features are available, the wizard is displayed
+    when creating a new file or project.
 
     Qt4VersionManager creates an instance of IFeatureProvider and provides Qt specific features for the available
     versions of Qt.
@@ -95,11 +97,11 @@
 /*!
     \fn bool Features::~contains(const Feature &feature)()
 
-    \returns true if the \param features is available.
+    Returns true if \a feature is available.
 */
 
 /*!
     \fn bool Features::~contains(const Features &features)()
 
-    \returns true if all \param features are available.
+    Returns true if all \a features are available.
 */

src/plugins/coreplugin/generatedfile.cpp

@@ -42,8 +42,8 @@ namespace Core {
     \class Core::GeneratedFile
     \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
+    The Wizard class checks whether each file already exists and
-    report any errors that may occur during creation of the files.
+    reports any errors that may occur during creation of the files.
 
     \sa Core::BaseFileWizardParameters, Core::BaseFileWizard, Core::StandardFileWizard
     \sa Core::Internal::WizardEventLoop

src/plugins/coreplugin/icore.cpp

@@ -37,7 +37,7 @@
 /*!
     \namespace Core
     \brief The Core namespace contains all classes that make up the Core plugin
-    which constitute the basic functionality of Qt Creator.
+    which constitute the basic functionality of \QC.
 */
 
 /*!
@@ -60,12 +60,14 @@
 /*!
     \fn void ICore::showNewItemDialog(const QString &title,
                                       const QList<IWizard *> &wizards,
-                                      const QString &defaultLocation = QString())
+                                      const QString &defaultLocation = QString(),
-    \brief Opens a dialog where the user can choose from a set of \a wizards that
+                                      const QVariantMap &extraVariables = QVariantMap())
-    create new files/classes/projects.
 
-    The \a title argument is shown as the dialogs title. The path where the
+    Opens a dialog where the user can choose from a set of \a wizards that
-    files will be created (if the user doesn't change it) is set
+    create new files, classes, or projects.
+
+    The \a title argument is shown as the dialog title. The path where the
+    files will be created (if the user does not change it) is set
     in \a defaultLocation. It defaults to the path of the file manager's
     current file.
 
@@ -73,11 +75,10 @@
 */
 
 /*!
-    \fn bool ICore::showOptionsDialog(const QString &group = QString(),
+    \fn bool ICore::showOptionsDialog(Id group, Id page, QWidget *parent = 0);
-                                      const QString &page = QString(),
+
-                                      QWidget *parent = 0)
+    Opens the application \gui Options (or \gui Preferences) dialog with preselected
-    \brief Opens the application options/preferences dialog with preselected
+    \a page in the specified \a group.
-    \a page in a specified \a group.
 
     The arguments refer to the string IDs of the corresponding IOptionsPage.
 */
@@ -89,16 +90,16 @@
                                    const QString &settingsId = QString(),
                                    QWidget *parent = 0);
 
-    \brief Show a warning message with a button that opens a settings page.
+    Shows a warning message with a button that opens a settings page.
 
     Should be used to display configuration errors and point users to the setting.
-    Returns true if the settings dialog was accepted.
+    Returns \c true if the settings dialog was accepted.
 */
 
 
 /*!
     \fn ActionManager *ICore::actionManager() const
-    \brief Returns the application's action manager.
+    Returns the application's action manager.
 
     The action manager is responsible for registration of menus and
     menu items and keyboard shortcuts.
@@ -112,16 +113,18 @@
 */
 
 /*!
-    \fn MessageManager *ICore::messageManager() const
+    \fn MessageManager *ICore::messageManager()
-    \brief Returns the application's message manager.
+
+    Returns the application's message manager.
 
     The message manager is the interface to the "General" output pane for
     general application debug messages.
 */
 
 /*!
-    \fn EditorManager *ICore::editorManager() const
+    \fn EditorManager *ICore::editorManager()
-    \brief Returns the application's editor manager.
+
+    Returns the application's editor manager.
 
     The editor manager handles all editor related tasks like opening
     documents, the stack of currently open documents and the currently
@@ -129,11 +132,12 @@
 */
 
 /*!
-    \fn ProgressManager *ICore::progressManager() const
+    \fn ProgressManager *ICore::progressManager()
-    \brief Returns the application's progress manager.
+
+    Returns the application's progress manager.
 
     Use the progress manager to register a concurrent task to
-    show a progress bar the way Qt Creator does it.
+    show a progress bar the way \QC does it.
 */
 
 /*!
@@ -143,7 +147,7 @@
 
 /*!
     \fn VariableManager *ICore::variableManager() const
-    \brief Returns the application's variable manager.
+    Returns the application's variable manager.
 
     The variable manager is used to register application wide string variables
     like \c MY_PROJECT_DIR such that strings like \c{somecommand ${MY_PROJECT_DIR}/sub}
@@ -151,19 +155,20 @@
 */
 
 /*!
-    \fn VcsManager *ICore::vcsManager() const
+    \fn VcsManager *ICore::vcsManager()
-    \brief Returns the application's vcs manager.
 
-    The vcs manager can be used to e.g. retrieve information about
+    Returns the application's version control system (VCS) manager.
+
+    The VCS manager can be used to retrieve information about
     the version control system used for a directory on hard disk.
     The actual functionality for a specific version control system
-    must be implemented in a IVersionControl object and registered in
+    must be implemented in an \c IVersionControl object and registered in
     the plugin manager's object pool.
 */
 
 /*!
     \fn ModeManager *ICore::modeManager() const
-    \brief Returns the application's mode manager.
+    Returns the application's mode manager.
 
     The mode manager handles everything related to the instances of IMode
     that were added to the plugin manager's object pool as well as their
@@ -172,33 +177,34 @@
 */
 
 /*!
-    \fn MimeDatabase *ICore::mimeDatabase() const
+    \fn MimeDatabase *ICore::mimeDatabase()
-    \brief Returns the application's mime database.
 
-    Use the mime database to manage mime types.
+    Uses the MIME database to manage MIME types.
 */
 
 /*!
-    \fn QSettings *ICore::settings(QSettings::Scope scope = QSettings::UserScope) const
+    \fn QSettings *ICore::settings(QSettings::Scope scope = QSettings::UserScope)
-    \brief Returns the application's main settings object.
+
+    Returns the application's main settings object.
 
     You can use it to retrieve or set application wide settings
     (in contrast to session or project specific settings).
 
-    If \a scope is QSettings::UserScope (the default), the
+    If \a scope is \c QSettings::UserScope (the default), the
     users settings will be read from the users settings, with
-    a fallback to global settings provided with Qt Creator.
+    a fallback to global settings provided with \QC.
 
-    If \a scope is QSettings::SystemScope, only the system settings
+    If \a scope is \c QSettings::SystemScope, only the system settings
-    shipped with the current version of Qt Creator will be read. This
+    shipped with the current version of \QC will be read. This
     functionality exists for internal purposes only.
 
     \see settingsDatabase()
 */
 
 /*!
-    \fn SettingsDatabase *ICore::settingsDatabase() const
+    \fn SettingsDatabase *ICore::settingsDatabase()
-    \brief Returns the application's settings database.
+
+    Returns the application's settings database.
 
     The settings database is meant as an alternative to the regular settings
     object. It is more suitable for storing large amounts of data. The settings
@@ -208,42 +214,48 @@
 */
 
 /*!
-    \fn QPrinter *ICore::printer() const
+    \fn QPrinter *ICore::printer()
-    \brief Returns the application's printer object.
+
+    Returns the application's printer object.
 
     Always use this printer object for printing, so the different parts of the
     application re-use its settings.
 */
 
 /*!
-    \fn QString ICore::resourcePath() const
+    \fn QString ICore::resourcePath()
-    \brief Returns the absolute path that is used for resources like
+
+    Returns the absolute path that is used for resources like
     project templates and the debugger macros.
 
     This abstraction is needed to avoid platform-specific code all over
-    the place, since e.g. on Mac the resources are part of the application bundle.
+    the place, since on Mac OS X, for example, the resources are part of the
+    application bundle.
 */
 
 
 /*!
-    \fn QString ICore::userResourcePath() const
+    \fn QString ICore::userResourcePath()
-    \brief Returns the absolute path in the users directory that is used for
+
+    Returns the absolute path in the users directory that is used for
     resources like project templates.
 
     Use this method for finding the place for resources that the user may
-    write to, e.g. to allow for custom palettes or templates.
+    write to, for example, to allow for custom palettes or templates.
 */
 
 /*!
-    \fn QMainWindow *ICore::mainWindow() const
+    \fn QWidget *ICore::mainWindow()
-    \brief Returns the main application window.
 
-    For use as dialog parent etc.
+    Returns the main application window.
+
+    For use as dialog parent, and so on.
 */
 
 /*!
-    \fn IContext *ICore::currentContextObject() const
+    \fn IContext *ICore::currentContextObject()
-    \brief Returns the context object of the current main context.
+
+    Returns the context object of the current main context.
 
     \sa ICore::updateAdditionalContexts()
     \sa ICore::addContextObject()
@@ -251,7 +263,7 @@
 
 /*!
     \fn void ICore::updateAdditionalContexts(const Context &remove, const Context &add)
-    \brief Change the currently active additional contexts.
+    Changes the currently active additional contexts.
 
     Removes the list of additional contexts specified by \a remove and adds the
     list of additional contexts specified by \a add.
@@ -261,7 +273,7 @@
 
 /*!
     \fn bool ICore::hasContext(int context) const
-    \brief Returns if the given \a context is currently one of the active contexts.
+    Returns whether the given \a context is currently one of the active contexts.
 
     \sa ICore::updateAdditionalContexts()
     \sa ICore::addContextObject()
@@ -269,7 +281,7 @@
 
 /*!
     \fn void ICore::addContextObject(IContext *context)
-    \brief Registers an additional \a context object.
+    Registers an additional \a context object.
 
     After registration this context object gets automatically the
     current context object whenever its widget gets focus.
@@ -281,7 +293,7 @@
 
 /*!
     \fn void ICore::removeContextObject(IContext *context)
-    \brief Unregisters a \a context object from the list of know contexts.
+    Unregisters a \a context object from the list of know contexts.
 
     \sa ICore::addContextObject()
     \sa ICore::updateAdditionalContexts()
@@ -291,9 +303,9 @@
 
 /*!
     \fn void ICore::openFiles(const QStringList &fileNames, OpenFilesFlags flags = None)
-    \brief Open all files from a list of \a fileNames like it would be
+    Opens all files from a list of \a fileNames like it would be
-    done if they were given to Qt Creator on the command line, or
+    done if they were given to \QC on the command line, or
-    they were opened via \gui{File|Open}.
+    they were opened via \gui File > \gui Open.
 */
 
 /*!
@@ -308,12 +320,12 @@
 
 /*!
     \fn void ICore::coreOpened()
-    \brief Emitted after all plugins have been loaded and the main window shown.
+    Indicates that all plugins have been loaded and the main window is shown.
 */
 
 /*!
     \fn void ICore::saveSettingsRequested()
-    \brief Emitted to signal that the user has requested that the global settings
+    Signals that the user has requested that the global settings
     should be saved to disk.
 
     At the moment that happens when the application is closed, and on \gui{Save All}.
@@ -321,29 +333,30 @@
 
 /*!
     \fn void ICore::optionsDialogRequested()
-    \brief Signal that allows plugins to perform actions just before the \gui{Tools|Options}
+    Enables plugins to perform actions just before the \gui Tools > \gui Options
     dialog is shown.
 */
 
 /*!
     \fn void ICore::coreAboutToClose()
-    \brief Plugins can do some pre-end-of-life actions when they get this signal.
+    Enables plugins to perform some pre-end-of-life actions.
 
     The application is guaranteed to shut down after this signal is emitted.
-    It's there as an addition to the usual plugin lifecycle methods, namely
+    It is there as an addition to the usual plugin lifecycle methods, namely
-    IPlugin::aboutToShutdown(), just for convenience.
+    \c IPlugin::aboutToShutdown(), just for convenience.
 */
 
 /*!
     \fn void ICore::contextAboutToChange(const QList<Core::IContext *> &context)
-    \brief Sent just before a new \a context becomes the current context
+    Indicates that a new \a context will shortly become the current context
-    (meaning that itself or one of its child widgets got focus).
+    (meaning that its widget got focus).
 */
 
 /*!
     \fn void ICore::contextChanged(Core::IContext *context, const Core::Context &additionalContexts)
-    \brief Sent just after a new \a context became the current context
+    Indicates that a new \a context just became the current context
-    (meaning that its widget got focus), or if the additional context ids changed.
+    (meaning that its widget got focus), or that the additional context ids
+    specified by \a additionalContexts changed.
 */
 
 #include "mainwindow.h"

src/plugins/coreplugin/id.cpp

@@ -54,7 +54,7 @@ namespace Core {
     and associated with a plain 7-bit-clean ASCII name used
     for display and persistency.
 
-    Each plugin that is distributed as part of Qt Creator has a
+    Each plugin that is distributed as part of \QC has a
     private range of 10000 UIDs that are guaranteed to be unique.
 
     Third party plugins are advised to construct ids from their
@@ -137,10 +137,10 @@ static int theId(const QByteArray &ba)
 /*!
     \fn Core::Id(int uid)
 
-    \brief Constructs an id given a UID.
+    Constructs an id given \a UID.
 
     The UID is an integer value that is unique within the running
-    Qt Creator process.
+    \QC process.
 
     It is the callers responsibility to ensure the uniqueness of
     the passed integer. The recommended approach is to use
@@ -152,9 +152,9 @@ static int theId(const QByteArray &ba)
 */
 
 /*!
-    Constructs an id given its associated name. The internal
+    Constructs an id given its associated \a name. The internal
     representation will be unspecified, but consistent within a
-    Qt Creator process.
+    \QC process.
 
 */
 Id::Id(const char *name)
@@ -248,7 +248,7 @@ Id Id::fromSetting(const QVariant &variant)
 
   This can be used to construct groups of ids logically
   belonging together. The associated internal name
-  will be generated by appending \c{suffix}.
+  will be generated by appending \a suffix.
 */
 
 Id Id::withSuffix(int suffix) const
@@ -284,7 +284,7 @@ Id Id::withSuffix(const QString &suffix) const
 
   This can be used to construct groups of ids logically
   belonging together. The associated internal name
-  will be generated by prepending \c{prefix}.
+  will be generated by prepending \a prefix.
 */
 
 Id Id::withPrefix(const char *prefix) const
@@ -332,9 +332,9 @@ bool Id::alphabeticallyBefore(Id other) const
 
 
 /*!
-  Convenience function to extract a part of the id string
+  Extracts a part of the id string
-  representation. This can be used to split off the base
+  representation. This function can be used to split off the base
-  part used when generating an id with \c{withSuffix()}.
+  part specified by \a baseId used when generating an id with \c{withSuffix()}.
 
   \sa withSuffix()
 */

src/plugins/coreplugin/mimedatabase.cpp

@@ -113,8 +113,8 @@ namespace Internal {
     \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"
+    This class exists to enable reading the file contents \e {on demand},
-    (as opposed to each mime type trying to open and read while checking).
+    as opposed to each mime type trying to open and read while checking.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -196,8 +196,8 @@ public:
     \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.
+    If the data does not contain any character below tab (9), it is detected as
-    Additionally, check on UTF16 byte order markers.
+    text. Additionally, UTF16 byte order markers are checked.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher
@@ -244,8 +244,8 @@ bool HeuristicTextMagicMatcher::matches(const QByteArray &data) const
     and offset specification.
 
     Stores the offset and provides conversion helpers.
-    Base class for implementations for "string" and "byte".
+    Base class for implementations for \c string and \c byte.
-    (Others like little16, big16, etc. can be created whenever there is a need.)
+    Others, such as \c little16 and \c big16, can be created when needed.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -419,7 +419,7 @@ bool MagicByteRule::matches(const QByteArray &data) const
     \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.
+    This class is used for rules parsed from XML files.
 
     \sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -528,17 +528,17 @@ bool MimeGlobPattern::matches(const QString &fileName) const
 
     \brief The MimeType class contains MIME type data used in \QC.
 
-    Contains most information from standard mime type XML database files.
+    Contains most information from standard MIME type XML database files.
 
-    Currently, magic of types "string", "bytes" is supported. In addition,
+    Currently, magic of types \c string anc \c bytes is supported. In addition,
-    C++ classes, derived from Core::IMagicMatcher can be added to check
+    C++ classes, derived from \c Core::IMagicMatcher can be added to check
     on contents.
 
-    In addition, the class provides a list of suffixes and a concept of the
+    The class provides a list of suffixes and a concept of a
-    'preferred suffix' (derived from glob patterns). This is used for example
+    \e {preferred suffix} (derived from glob patterns). This is used for example
-    to be able to configure the suffix used for C++-files in Qt Creator.
+    to be able to configure the suffix used for C++ files in \QC.
 
-    Mime XML looks like:
+    MIME type XML files look like follows:
     \code
     <?xml version="1.0" encoding="UTF-8"?>
     <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
@@ -929,7 +929,8 @@ namespace Internal {
     \brief The BaseMimeTypeParser class provides a generic parser for a
     sequence of <mime-type>.
 
-    Calls abstract handler function process for MimeType it finds.
+    This class calls the abstract handler function process for the MIME types
+    it finds.
 
     \sa Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
     \sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
@@ -1197,37 +1198,38 @@ MimeMapEntry::MimeMapEntry(const MimeType &t, int aLevel) :
 
     The class is protected by a QMutex and can therefore be accessed by threads.
 
-    A good testcase is to run it over \c '/usr/share/mime/<*>/<*>.xml' on Linux.
+    A good testcase is to run it over \c {/usr/share/mime/<*>/<*>.xml} on Linux.
 
-    When adding a "text/plain" to it, the mimetype will receive a magic matcher
+    When adding a \c{text/plain} to it, the MIME type will receive a magic matcher
     that checks for text files that do not match the globs by heuristics.
 
     \section1 Design Considerations
 
     Storage requirements:
     \list
-    \li Must be robust in case of incomplete hierarchies, dangling entries
+    \li Must be robust in case of incomplete hierarchies and dangling entries.
-    \li Plugins will not load and register their mime types in order of inheritance.
+    \li Plugins will not load and register their MIME types in order of
-    \li Multiple inheritance (several subClassesOf) can occur
+        inheritance.
-    \li Provide quick lookup by name
+    \li Multiple inheritance (several subClassesOf) can occur.
+    \li Provide quick lookup by name.
     \li Provide quick lookup by file type.
     \endlist
 
-    This basically rules out some pointer-based tree, so the structure chosen is:
+    This basically rules out a pointer-based tree, so the structure chosen is:
     \list
-    \li An alias map QString->QString for mapping aliases to types
+    \li An alias map \c {QString->QString} for mapping aliases to types.
-    \li A Map QString->MimeMapEntry for the types (MimeMapEntry being a pair of
+    \li A map \c {QString->MimeMapEntry} for the types (MimeMapEntry being a pair of
        MimeType and (hierarchy) level.
-    \li A map  QString->QString representing parent->child relations (enabling
+    \li A map  \c {QString->QString} representing parent to child relations (enabling
-       recursing over children)
+       recursing over children).
     \li Using strings avoids dangling pointers.
     \endlist
 
-    The hierarchy level is used for mapping by file types. When findByFile()
+    The hierarchy level is used for mapping by file types. When \c findByFile()
-    is first called after addMimeType() it recurses over the hierarchy and sets
+    is first called after \c addMimeType(), it recurses over the hierarchy and sets
     the hierarchy level of the entries accordingly (0 toplevel, 1 first
     order...). It then does several passes over the type map, checking the
-    globs for maxLevel, maxLevel-1....until it finds a match (idea being to
+    globs for maxLevel, maxLevel-1....until it finds a match (the idea being
     to check the most specific types first). Starting a recursion from the
     leaves is not suitable since it will hit parent nodes several times.
 

src/plugins/coreplugin/textdocument.cpp

@@ -38,7 +38,7 @@
     \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
+    This class stores the format obtained from read operations and uses that when writing
     out files, thus ensuring that CRLF/encodings are preserved.
 
     \sa Utils::TextFileUtils
@@ -83,7 +83,7 @@ QByteArray TextDocument::decodingErrorSample() const
 }
 
 /*!
-    \brief Writes out text using the format obtained from the last read.
+    Writes out text using the format obtained from the last read.
 */
 
 bool TextDocument::write(const QString &fileName, const QString &data, QString *errorMessage) const
@@ -92,7 +92,7 @@ bool TextDocument::write(const QString &fileName, const QString &data, QString *
 }
 
 /*!
-    \brief Writes out text using a custom format obtained.
+    Writes out text using a custom \a format.
 */
 
 bool TextDocument::write(const QString &fileName, const Utils::TextFileFormat &format, const QString &data, QString *errorMessage) const
@@ -103,7 +103,7 @@ bool TextDocument::write(const QString &fileName, const Utils::TextFileFormat &f
 }
 
 /*!
-    \brief Autodetect format and read in a text file.
+    Autodetects format and reads in the text file specified by \a fileName.
 */
 
 TextDocument::ReadResult TextDocument::read(const QString &fileName, QStringList *plainTextList, QString *errorString)
@@ -115,7 +115,7 @@ TextDocument::ReadResult TextDocument::read(const QString &fileName, QStringList
 }
 
 /*!
-    \brief Autodetect format and read in a text file.
+    Autodetects format and reads in the text file specified by \a fileName.
 */
 
 TextDocument::ReadResult TextDocument::read(const QString &fileName, QString *plainText, QString *errorString)
@@ -146,7 +146,7 @@ void TextDocument::switchUtf8Bom()
 }
 
 /*!
-    \brief Returns the format obtained from the last call to read().
+    Returns the format obtained from the last call to \c read().
 */
 
 Utils::TextFileFormat TextDocument::format() const