Doc: edit projectexplorer API docs

Fix grammar, punctuation, and style issues. Use standard wording for
QDoc commands. Remove \brief commands from function descriptions.
Move some function descriptions directly above the functions, so
that the \fn command can be removed.

Change-Id: Iedf4f0041af24541a982241f99bd4906e86af916
Reviewed-by: Daniel Teske <daniel.teske@digia.com>

src/plugins/projectexplorer/abstractprocessstep.cpp

@@ -72,18 +72,18 @@ using namespace ProjectExplorer;
 /*!
     \fn void ProjectExplorer::AbstractProcessStep::setEnabled(bool b)
 
-    \brief Enables or disables a BuildStep.
+    Enables or disables a BuildStep.
 
     Disabled BuildSteps immediately return true from their run method.
-    Should be called from init()
+    Should be called from init().
 */
 
 /*!
     \fn ProcessParameters *ProjectExplorer::AbstractProcessStep::processParameters()
 
-    \brief Obtain a reference to the parameters for the actual process to run.
+    Obtains a reference to the parameters for the actual process to run.
 
-     Should be used in init()
+     Should be used in init().
 */
 
 AbstractProcessStep::AbstractProcessStep(BuildStepList *bsl, const Core::Id id) :
@@ -110,7 +110,7 @@ AbstractProcessStep::~AbstractProcessStep()
 }
 
 /*!
-     \brief Delete all existing output parsers and start a new chain with the
+     Deletes all existing output parsers and starts a new chain with the
      given parser.
 
      Derived classes need to call this function.
@@ -131,7 +131,7 @@ void AbstractProcessStep::setOutputParser(ProjectExplorer::IOutputParser *parser
 }
 
 /*!
-    \brief Append the given output parser to the existing chain of parsers.
+    Appends the given output parser to the existing chain of parsers.
 */
 
 void AbstractProcessStep::appendOutputParser(ProjectExplorer::IOutputParser *parser)
@@ -155,7 +155,7 @@ bool AbstractProcessStep::ignoreReturnValue()
 }
 
 /*!
-    \brief If ignoreReturnValue is set to true, then the abstractprocess step will
+    If \a ignoreReturnValue is set to true, then the abstractprocess step will
     return success even if the return value indicates otherwise.
 
     Should be called from init.
@@ -167,8 +167,8 @@ void AbstractProcessStep::setIgnoreReturnValue(bool b)
 }
 
 /*!
-    \brief Reimplemented from BuildStep::init(). You need to call this from
+    Reimplemented from BuildStep::init(). You need to call this from
-    YourBuildStep::init()
+    YourBuildStep::init().
 */
 
 bool AbstractProcessStep::init()
@@ -177,7 +177,8 @@ bool AbstractProcessStep::init()
 }
 
 /*!
-    \brief Reimplemented from BuildStep::init(). You need to call this from YourBuildStep::run()
+    Reimplemented from BuildStep::init(). You need to call this from
+    YourBuildStep::run().
 */
 
 void AbstractProcessStep::run(QFutureInterface<bool> &fi)
@@ -241,9 +242,10 @@ void AbstractProcessStep::cleanUp()
 }
 
 /*!
-    \brief Called after the process is started.
+    Called after the process is started.
 
-    The default implementation adds a process started message to the output message
+    The default implementation adds a process-started message to the output
+    message.
 */
 
 void AbstractProcessStep::processStarted()
@@ -255,9 +257,9 @@ void AbstractProcessStep::processStarted()
 }
 
 /*!
-    \brief Called after the process Finished.
+    Called after the process is finished.
 
-    The default implementation adds a line to the output window
+    The default implementation adds a line to the output window.
 */
 
 void AbstractProcessStep::processFinished(int exitCode, QProcess::ExitStatus status)
@@ -279,9 +281,9 @@ void AbstractProcessStep::processFinished(int exitCode, QProcess::ExitStatus sta
 }
 
 /*!
-    \brief Called if the process could not be started.
+    Called if the process could not be started.
 
-    By default adds a message to the output window.
+    By default, adds a message to the output window.
 */
 
 void AbstractProcessStep::processStartupFailed()
@@ -293,7 +295,7 @@ void AbstractProcessStep::processStartupFailed()
 }
 
 /*!
-    \brief Called to test whether a prcess succeeded or not.
+    Called to test whether a process succeeded or not.
 */
 
 bool AbstractProcessStep::processSucceeded(int exitCode, QProcess::ExitStatus status)
@@ -311,7 +313,7 @@ void AbstractProcessStep::processReadyReadStdOutput()
 }
 
 /*!
-    \brief Called for each line of output on stdOut().
+    Called for each line of output on stdOut().
 
     The default implementation adds the line to the application output window.
 */
@@ -333,9 +335,9 @@ void AbstractProcessStep::processReadyReadStdError()
 }
 
 /*!
-    \brief Called for each line of output on StdErrror().
+    Called for each line of output on StdErrror().
 
-    The default implementation adds the line to the application output window
+    The default implementation adds the line to the application output window.
 */
 
 void AbstractProcessStep::stdError(const QString &line)

src/plugins/projectexplorer/buildconfigurationmodel.cpp

@@ -38,8 +38,8 @@ using namespace ProjectExplorer;
     \brief The BuildConfigurationModel class is a model to represent the build
     configurations of a target.
 
-    To be used in for the drop down of comboboxes.
+    To be used in the dropdown lists of comboboxes.
-    Does automatically adjust itself to added and removed BuildConfigurations
+    Automatically adjusts itself to added and removed BuildConfigurations.
     Very similar to the Run Configuration Model.
 
     TODO might it possible to share code without making the code a complete mess.

src/plugins/projectexplorer/buildstep.cpp

@@ -60,15 +60,15 @@
 /*!
     \fn bool ProjectExplorer::BuildStep::init()
 
-    This function is run in the gui thread,
+    This function is run in the GUI thread. Use it to retrieve any information
-    use it to retrieve any information that you need in run()
+    that you need in the run() function.
 */
 
 /*!
     \fn void ProjectExplorer::BuildStep::run(QFutureInterface<bool> &fi)
 
-    Reimplement this. This function is called when the target is build.
+    Reimplement this function. It is called when the target is built.
-    By default this function is NOT run in the gui thread. It runs in its
+    By default, this function is NOT run in the GUI thread, but runs in its
     own thread. If you need an event loop, you need to create one.
     This function should block until the task is done
 
@@ -77,48 +77,37 @@
     fi.reportResult(true);
     \endcode
 
-    By returning true from \sa runInGuiThread() this function is called in the
+    By returning \c true from runInGuiThread(), this function is called in
-    gui thread. Then the function should not block and instead the
+    the GUI thread. Then the function should not block and instead the
     finished() signal should be emitted.
+
+    \sa runInGuiThread()
 */
 
 /*!
     \fn BuildStepConfigWidget *ProjectExplorer::BuildStep::createConfigWidget()
 
-    Returns the Widget shown in the target settings dialog for this buildStep;
+    Returns the Widget shown in the target settings dialog for this build step.
-    ownership is transferred to the caller.
+    Ownership is transferred to the caller.
-*/
-
-/*!
-    \fn bool ProjectExplorer::BuildStep::immutable() const
-
-    If this function returns true, the user can't delete this BuildStep for this target
-    and the user is prevented from changing the order immutable steps are run
-    the default implementation returns false.
 */
 
 /*!
     \fn  void ProjectExplorer::BuildStep::addTask(const ProjectExplorer::Task &task)
-    \brief Add a task.
+    Adds \a task.
 */
 
 /*!
     \fn  void addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format,
               ProjectExplorer::BuildStep::OutputNewlineSetting newlineSetting)
 
-    The string is added to the generated output, usually in the output window.
+    The \a string is added to the generated output, usually in the output pane.
     It should be in plain text, with the format in the parameter.
 */
 
-/*!
-    \fn void ProjectExplorer::BuildStep::cancel() const
-
-    This function needs to be reimplemented only for BuildSteps that return false from \sa runInGuiThread.
-*/
 
 /*!
     \fn  void ProjectExplorer::BuildStep::finished()
-    \brief This signal needs to be emitted if the BuildStep runs in the gui thread.
+    This signal needs to be emitted if the build step runs in the GUI thread.
 */
 
 static const char buildStepEnabledKey[] = "ProjectExplorer.BuildStep.Enabled";
@@ -180,6 +169,12 @@ Project *BuildStep::project() const
     return target()->project();
 }
 
+/*!
+    If this function returns \c true, the user cannot delete this build step for
+    this target and the user is prevented from changing the order in which
+    immutable steps are run. The default implementation returns \c false.
+*/
+
 bool BuildStep::immutable() const
 {
     return false;
@@ -190,6 +185,12 @@ bool BuildStep::runInGuiThread() const
     return false;
 }
 
+/*!
+    This function needs to be reimplemented only for build steps that return
+    \c false from runInGuiThread().
+
+    \sa runInGuiThread()
+*/
 void BuildStep::cancel()
 {
     // Do nothing

src/plugins/projectexplorer/deployconfigurationmodel.cpp

@@ -39,8 +39,8 @@ using namespace ProjectExplorer;
     \brief The DeployConfigurationModel class provides a model to represent
     the run configurations of a target.
 
-    To be used in for the drop down of comboboxes.  Does automatically adjust
+    To be used in drop down lists of comboboxes. Automatically adjusts
-    itself to added and removed DeployConfigurations
+    itself to added and removed deploy configurations.
 */
 
 class DeployConfigurationComparer

src/plugins/projectexplorer/gcctoolchain.cpp

@@ -648,7 +648,7 @@ void GccToolChain::setPlatformCodeGenFlags(const QStringList &flags)
 }
 
 /*!
-    \brief code gen flags that have to be passed to the compiler
+    Code gen flags that have to be passed to the compiler.
  */
 QStringList GccToolChain::platformCodeGenFlags() const
 {
@@ -664,9 +664,9 @@ void GccToolChain::setPlatformLinkerFlags(const QStringList &flags)
 }
 
 /*!
-    \brief flags that have to be passed to the linker
+    Flags that have to be passed to the linker.
 
-    for example -arch armv7...
+    For example: \c{-arch armv7}
  */
 QStringList GccToolChain::platformLinkerFlags() const
 {

src/plugins/projectexplorer/ioutputparser.cpp

@@ -42,81 +42,86 @@
 /*!
     \fn void ProjectExplorer::IOutputParser::appendOutputParser(IOutputParser *parser)
 
-    \brief Append a subparser to this parser, of which IOutputParser will take ownership.
+    Appends a subparser to this parser, of which IOutputParser will take
+    ownership.
 */
 
 /*!
     \fn IOutputParser *ProjectExplorer::IOutputParser::takeOutputParserChain()
 
-    \brief Remove the appended outputparser chain from this parser, transferring
+    Removes the appended outputparser chain from this parser, transferring
            ownership of the parser chain to the caller.
 */
 
 /*!
     \fn IOutputParser *ProjectExplorer::IOutputParser::childParser() const
 
-    \brief Return the head of this parsers output parser children, IOutputParser keeps ownership.
+    Returns the head of this parser's output parser children. IOutputParser
+    keeps ownership.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::stdOutput(const QString &line)
 
-   \brief Called once for each line if standard output to parse.
+   Called once for each line if standard output to parse.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::stdError(const QString &line)
 
-   \brief Called once for each line if standard error to parse.
+   Called once for each line if standard error to parse.
 */
 
 /*!
    \fn bool ProjectExplorer::IOutputParser::hasFatalErrors() const
 
-   \brief This is mainly a symbian specific quirk.
+   This is mainly a Symbian specific quirk.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format)
 
-   \brief Should be emitted whenever some additional information should be added to the output.
+   Should be emitted whenever some additional information should be added to the
+   output.
 
-   Note: This is additional information. There is no need to add each line!
+   \note This is additional information. There is no need to add each line.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::addTask(const ProjectExplorer::Task &task)
 
-   \brief Should be emitted for each task seen in the output.
+   Should be emitted for each task seen in the output.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::outputAdded(const QString &string, ProjectExplorer::BuildStep::OutputFormat format)
 
-   \brief Subparsers have their addOutput signal connected to this slot.
+   Subparsers have their addOutput signal connected to this slot.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::outputAdded(const QString &string, ProjectExplorer::BuildStep::OutputFormat format)
 
-   \brief This method can be overwritten to change the string.
+   This method can be overwritten to change the string.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::taskAdded(const ProjectExplorer::Task &task)
 
-   \brief Subparsers have their addTask signal connected to this slot.
+   Subparsers have their addTask signal connected to this slot.
    This method can be overwritten to change the task.
 */
 
 /*!
    \fn void ProjectExplorer::IOutputParser::doFlush()
 
-   \brief This method is called whenever a parser is supposed to flush his state.
+   Instructs a parser to flush its state.
-   Parsers may have state (e.g. because they need to aggregate several lines into one task). This
+   Parsers may have state (for example, because they need to aggregate several
+   lines into one task). This
    method is called when this state needs to be flushed out to be visible.
 
-   doFlush() is called by flush(). flush() is called on childparsers whenever a new task is added.
+   doFlush() is called by flush(). flush() is called on child parsers
+   whenever a new task is added.
    It is also called once when all input has been parsed.
 */
 

src/plugins/projectexplorer/processparameters.cpp

@@ -57,7 +57,7 @@ ProcessParameters::ProcessParameters() :
 }
 
 /*!
-    \brief Sets the executable to run.
+    Sets the executable to run.
 */
 
 void ProcessParameters::setCommand(const QString &cmd)
@@ -67,7 +67,7 @@ void ProcessParameters::setCommand(const QString &cmd)
 }
 
 /*!
-    \brief Sets the command line arguments used by the process
+    Sets the command line arguments used by the process.
 */
 
 void ProcessParameters::setArguments(const QString &arguments)
@@ -77,8 +77,9 @@ void ProcessParameters::setArguments(const QString &arguments)
 }
 
 /*!
-    \brief Sets the workingDirectory for the process for a buildConfiguration
+    Sets the \a workingDirectory for the process for a build configuration.
-    should be called from init()
+
+    Should be called from init().
 */
 
 void ProcessParameters::setWorkingDirectory(const QString &workingDirectory)
@@ -89,20 +90,21 @@ void ProcessParameters::setWorkingDirectory(const QString &workingDirectory)
 
 /*!
     \fn void ProjectExplorer::ProcessParameters::setEnvironment(const Utils::Environment &env)
-    \brief Set the Environment for running the command
+    Sets the environment \a env for running the command.
 
-    Should be called from init()
+    Should be called from init().
 */
 
 /*!
    \fn  void ProjectExplorer::ProcessParameters::setMacroExpander(Utils::AbstractMacroExpander *mx)
-   \brief Set the macro expander to use on the command, arguments and working dir.
+   Sets the macro expander \a mx to use on the command, arguments, and working
+   dir.
 
-   Note that the caller retains ownership of the object.
+   \note The caller retains ownership of the object.
 */
 
 /*!
-    \brief Get the fully expanded working directory.
+    Gets the fully expanded working directory.
 */
 
 QString ProcessParameters::effectiveWorkingDirectory() const
@@ -117,7 +119,7 @@ QString ProcessParameters::effectiveWorkingDirectory() const
 }
 
 /*!
-    \brief Get the fully expanded command name to run
+    Gets the fully expanded command name to run.
 */
 
 QString ProcessParameters::effectiveCommand() const
@@ -136,7 +138,7 @@ QString ProcessParameters::effectiveCommand() const
 }
 
 /*!
-    \brief True if effectiveCommand() would return only a fallback.
+    Returns \c true if effectiveCommand() would return only a fallback.
 */
 
 bool ProcessParameters::commandMissing() const

src/plugins/projectexplorer/project.cpp

@@ -51,15 +51,17 @@
 /*!
    \fn void ProjectExplorer::Project::environmentChanged()
 
-   \brief Convenience signal emitted if the activeBuildConfiguration emits environmentChanged
+   A convenience signal emitted if activeBuildConfiguration emits
-   or if the activeBuildConfiguration changes (including due to the active target changing).
+   environmentChanged or if the active build configuration changes
+   (including due to the active target changing).
 */
 
 /*!
    \fn void ProjectExplorer::Project::buildConfigurationEnabledChanged()
 
-   \brief Convenience signal emitted if the activeBuildConfiguration emits isEnabledChanged()
+   A convenience signal emitted if activeBuildConfiguration emits
-   or if the activeBuildConfiguration changes (including due to the active target changing).
+   isEnabledChanged() or if the active build configuration changes
+   (including due to the active target changing).
 */
 
 namespace {
@@ -300,14 +302,14 @@ bool Project::restoreSettings()
 
 
 /*!
-    \brief Serialize all data into a QVariantMap.
+    Serializes all data into a QVariantMap.
 
     This map is then saved in the .user file of the project.
     Just put all your data into the map.
 
     \note Do not forget to call your base class' toMap method.
     \note Do not forget to call setActiveBuildConfiguration when
-          creating new BuilConfigurations.
+    creating new build configurations.
 */
 
 QVariantMap Project::toMap() const

src/plugins/projectexplorer/projectexplorer.cpp

@@ -127,12 +127,13 @@
 
 /*!
     \namespace ProjectExplorer
-    ProjectExplorer plugin namespace
+    The ProjectExplorer namespace contains the classes to explore projects.
 */
 
 /*!
     \namespace ProjectExplorer::Internal
-    Internal namespace of the ProjectExplorer plugin
+    The ProjectExplorer::Internal namespace is the internal namespace of the
+    ProjectExplorer plugin.
     \internal
 */
 

src/plugins/projectexplorer/projectfilewizardextension.cpp

@@ -68,10 +68,10 @@
     \brief The ProjectFileWizardExtension class implements the post-file
     generating steps of a project wizard.
 
-    Offers:
+    This class provides the following functions:
     \list
     \li Add to a project file (*.pri/ *.pro)
-    \li Initialize a version control repository (unless the path is already
+    \li Initialize a version control system repository (unless the path is already
         managed) and do 'add' if the VCS supports it.
     \endlist
 

src/plugins/projectexplorer/projectnodes.cpp

@@ -89,9 +89,10 @@ void Node::emitNodeSortKeyChanged()
 }
 
 /*!
- * \brief The path of the file representing this node.
+ * The path of the file representing this node.
  *
- * This method does not emit any signals, that has to be done by the calling class!
+ * This method does not emit any signals. That has to be done by the calling
+ * class.
  */
 void Node::setPath(const QString &path)
 {
@@ -110,7 +111,8 @@ NodeType Node::nodeType() const
 }
 
 /*!
-  \brief Project that owns & manages the node. It's the first project in list of ancestors.
+  The project that owns and manages the node. It is the first project in the list
+  of ancestors.
   */
 ProjectNode *Node::projectNode() const
 {
@@ -118,7 +120,7 @@ ProjectNode *Node::projectNode() const
 }
 
 /*!
-  \brief Parent in node hierarchy.
+  The parent in the node hierarchy.
   */
 FolderNode *Node::parentFolderNode() const
 {
@@ -126,7 +128,7 @@ FolderNode *Node::parentFolderNode() const
 }
 
 /*!
-  \brief Path of file or folder in the filesystem the node represents.
+  The path of the file or folder in the filesystem the node represents.
   */
 QString Node::path() const
 {
@@ -183,7 +185,9 @@ void Node::setParentFolderNode(FolderNode *parentFolder)
 /*!
   \class ProjectExplorer::FileNode
 
-  \brief In-memory presentation of a file. All FileNode's are leaf nodes.
+  \brief The FileNode class is an in-memory presentation of a file.
+
+  All file nodes are leaf nodes.
 
   \sa ProjectExplorer::FolderNode, ProjectExplorer::ProjectNode
 */
@@ -203,7 +207,7 @@ FileType FileNode::fileType() const
 }
 
 /*!
-  \brief Returns true if the file is automatically generated by a compile step.
+  Returns \c true if the file is automatically generated by a compile step.
   */
 bool FileNode::isGenerated() const
 {
@@ -230,7 +234,7 @@ FolderNode::~FolderNode()
 }
 
 /*!
-    \brief The display name that should be used in a view.
+    Contains the display name that should be used in a view.
     \sa setFolderName()
  */
 
@@ -240,7 +244,8 @@ QString FolderNode::displayName() const
 }
 
 /*!
-  \brief The icon that should be used in a view. Default is the directory icon (QStyle::S_PDirIcon).
+  Contains the icon that should be used in a view. Default is the directory icon
+ (QStyle::S_PDirIcon).
   s\a setIcon()
  */
 QIcon FolderNode::icon() const
@@ -329,15 +334,15 @@ int VirtualFolderNode::priority() const
 /*!
   \class ProjectExplorer::ProjectNode
 
-  \brief In-memory presentation of a Project.
+  \brief The ProjectNode class is an in-memory presentation of a Project.
 
-  A concrete subclass must implement the "persistent" stuff
+  A concrete subclass must implement the persistent data.
 
   \sa ProjectExplorer::FileNode, ProjectExplorer::FolderNode
 */
 
 /*!
-  \brief Creates uninitialized ProjectNode object.
+  Creates an uninitialized project node object.
   */
 ProjectNode::ProjectNode(const QString &projectFilePath)
         : FolderNode(projectFilePath)
@@ -407,7 +412,7 @@ QList<NodesWatcher*> ProjectNode::watchers() const
 }
 
 /*!
-   \brief Registers a watcher for the current project & all sub projects
+   Registers \a watcher for the current project and all subprojects.
 
    It does not take ownership of the watcher.
 */
@@ -424,7 +429,7 @@ void ProjectNode::registerWatcher(NodesWatcher *watcher)
 }
 
 /*!
-    \brief Removes a watcher for the current project & all sub projects.
+    Removes \a watcher from the current project and all subprojects.
 */
 void ProjectNode::unregisterWatcher(NodesWatcher *watcher)
 {
@@ -444,7 +449,8 @@ void ProjectNode::accept(NodesVisitor *visitor)
 }
 
 /*!
-  \brief Adds project nodes to the hierarchy and emits the corresponding signals.
+  Adds project nodes specified by \a subProjects to the node hierarchy and
+  emits the corresponding signals.
   */
 void ProjectNode::addProjectNodes(const QList<ProjectNode*> &subProjects)
 {
@@ -474,9 +480,10 @@ void ProjectNode::addProjectNodes(const QList<ProjectNode*> &subProjects)
 }
 
 /*!
-  \brief Remove project nodes from the hierarchy and emits the corresponding signals.
+  Removes project nodes specified by \a subProjects from the node hierarchy
+  and emits the corresponding signals.
 
-  All objects in the argument list are deleted.
+  All objects in the \a subProjects list are deleted.
 */
 
 void ProjectNode::removeProjectNodes(const QList<ProjectNode*> &subProjects)
@@ -515,7 +522,8 @@ void ProjectNode::removeProjectNodes(const QList<ProjectNode*> &subProjects)
 }
 
 /*!
-  \brief Adds folder nodes to the hierarchy and emits the corresponding signals.
+  Adds folder nodes specified by \a subFolders to the node hierarchy below
+  \a parentFolder and emits the corresponding signals.
 */
 void ProjectNode::addFolderNodes(const QList<FolderNode*> &subFolders, FolderNode *parentFolder)
 {
@@ -560,9 +568,10 @@ void ProjectNode::addFolderNodes(const QList<FolderNode*> &subFolders, FolderNod
 }
 
 /*!
-  \brief Remove file nodes from the hierarchy and emits the corresponding signals.
+  Removes file nodes specified by \a subFolders from the node hierarchy and emits
+  the corresponding signals.
 
-  All objects in the subFolders list are deleted.
+  All objects in the \a subFolders list are deleted.
 */
 void ProjectNode::removeFolderNodes(const QList<FolderNode*> &subFolders,
                                    FolderNode *parentFolder)
@@ -600,9 +609,11 @@ void ProjectNode::removeFolderNodes(const QList<FolderNode*> &subFolders,
 }
 
 /*!
-  \brief Adds file nodes to the internal list and emits the corresponding signals.
+  Adds file nodes specified by \a files to the internal list in the location
+  specified by \a folder and emits the corresponding signals.
 
-  This method should be called within an implementation of the public method addFiles.
+  This method should be called within an implementation of the public method
+  addFiles.
 */
 
 void ProjectNode::addFileNodes(const QList<FileNode*> &files, FolderNode *folder)
@@ -643,10 +654,11 @@ void ProjectNode::addFileNodes(const QList<FileNode*> &files, FolderNode *folder
 }
 
 /*!
-  \brief Remove file nodes from the internal list and emits the corresponding signals.
+  Removes \a files from the internal list and emits the corresponding signals.
 
-  All objects in the argument list are deleted.
+  All objects in the \a files list are deleted.
-  This method should be called within an implementation of the public method removeFiles.
+  This method should be called within an implementation of the public method
+  removeFiles.
 */
 
 void ProjectNode::removeFileNodes(const QList<FileNode*> &files, FolderNode *folder)
@@ -705,7 +717,7 @@ QList<NodesWatcher*> SessionNode::watchers() const
 }
 
 /*!
-   \brief Registers a watcher for the complete session tree.
+   Registers \a watcher for the complete session tree.
    It does not take ownership of the watcher.
 */
 
@@ -721,7 +733,7 @@ void SessionNode::registerWatcher(NodesWatcher *watcher)
 }
 
 /*!
-    \brief Removes a watcher from the complete session tree
+    Removes \a watcher from the complete session tree.
 */
 
 void SessionNode::unregisterWatcher(NodesWatcher *watcher)
@@ -817,17 +829,18 @@ void SessionNode::watcherDestroyed(QObject *watcher)
 /*!
   \class ProjectExplorer::NodesWatcher
 
-  \brief NodesWatcher lets you keep track of changes in the tree.
+  \brief The NodesWatcher class enables you to keep track of changes in the
+  tree.
 
   Add a watcher by calling ProjectNode::registerWatcher() or
   SessionNode::registerWatcher(). Whenever the tree underneath the
-  ProectNode or SessionNode changes (e.g. nodes are added/removed),
+  project node or session node changes (for example, nodes are added or removed),
-  the corresponding signals of the NodesWatcher are emitted.
+  the corresponding signals of the watcher are emitted.
   Watchers can be removed from the complete tree or a subtree
   by calling ProjectNode::unregisterWatcher and
   SessionNode::unregisterWatcher().
 
-  The NodesWatcher is similar to the Observer in the
+  The NodesWatcher class is similar to the Observer class in the
   well-known Observer pattern (Booch et al).
 
   \sa ProjectExplorer::Node

src/plugins/projectexplorer/runconfiguration.cpp

@@ -66,8 +66,8 @@ const char USE_MULTIPROCESS_KEY[] = "RunConfiguration.UseMultiProcess";
     \class ProjectExplorer::ProcessHandle
     \brief The ProcessHandle class is a helper class to describe a process.
 
-    Encapsulates parameters of a running process, local (PID) or remote (to be done,
+    Encapsulates parameters of a running process, local (PID) or remote (to be
-    address, port, etc).
+    done, address, port, and so on).
 */
 
 ProcessHandle::ProcessHandle(quint64 pid) :
@@ -105,7 +105,8 @@ bool ProcessHandle::equals(const ProcessHandle &rhs) const
 
 
 /*!
-    \brief Returns the widget used to configure this run configuration. Ownership is transferred to the caller
+    Returns the widget used to configure this run configuration. Ownership is
+    transferred to the caller.
 */
 RunConfigWidget *IRunConfigurationAspect::createConfigurationWidget()
 {
@@ -179,7 +180,7 @@ void RunConfiguration::ctor()
 }
 
 /*!
-    \brief Used to find out whether a runconfiguration is enabled
+    Checks whether a run configuration is enabled.
 */
 
 bool RunConfiguration::isEnabled() const
@@ -256,13 +257,14 @@ bool RunConfiguration::fromMap(const QVariantMap &map)
     \brief The IRunConfigurationAspect class provides an additional
     configuration aspect.
 
-    Aspects are a mechanism to add RunControl-specific options to a RunConfiguration without
+    Aspects are a mechanism to add RunControl-specific options to a run
-    subclassing the RunConfiguration for every addition, preventing a combinatorical explosion
+    configuration without subclassing the run configuration for every addition.
-    of subclasses or the need to add all options to the base class.
+    This prevents a combinatorial explosion of subclasses and eliminates
+    the need to add all options to the base class.
 */
 
 /*!
-    \brief Return extra aspects.
+    Returns extra aspects.
 
     \sa ProjectExplorer::IRunConfigurationAspect
 */
@@ -286,23 +288,28 @@ Utils::OutputFormatter *RunConfiguration::createOutputFormatter() const
     settings.
 
     The run configuration factory is used for restoring run configurations from
-    settings. And used to create new runconfigurations in the "Run Settings" Dialog.
+    settings and for creating new run configurations in the \gui {Run Settings}
-    For the first case, bool canRestore(Target *parent, const QString &id) and
+    dialog.
-    RunConfiguration* create(Target *parent, const QString &id) are used.
+    To restore run configurations, use the
-    For the second type, the functions QStringList availableCreationIds(Target *parent) and
+    \c {bool canRestore(Target *parent, const QString &id)}
-    QString displayNameForType(const QString&) are used to generate a list of creatable
+    and \c {RunConfiguration* create(Target *parent, const QString &id)}
-    RunConfigurations, and create(..) is used to create it.
+    functions.
+
+    To generate a list of creatable run configurations, use the
+    \c {QStringList availableCreationIds(Target *parent)} and
+    \c {QString displayNameForType(const QString&)} functions. To create a
+    run configuration, use \c create().
 */
 
 /*!
     \fn QStringList ProjectExplorer::IRunConfigurationFactory::availableCreationIds(Target *parent) const
 
-    \brief Used to show the list of possible additons to a target, returns a list of types.
+    Shows the list of possible additions to a target. Returns a list of types.
 */
 
 /*!
-    \fn QString ProjectExplorer::IRunConfigurationFactory::displayNameForId(const QString &id) const
+    \fn QString ProjectExplorer::IRunConfigurationFactory::displayNameForId(const Core::Id id) const
-    \brief Used to translate the types to names to display to the user.
+    Translates the types to names to display to the user.
 */
 
 IRunConfigurationFactory::IRunConfigurationFactory(QObject *parent) :
@@ -378,21 +385,15 @@ QList<IRunConfigurationFactory *> IRunConfigurationFactory::find(Target *parent)
     run configuration.
 */
 
-/*!
-    \fn IRunConfigurationAspect *ProjectExplorer::IRunControlFactory::createRunConfigurationAspect()
-    \brief Return an IRunConfigurationAspect to carry options for RunControls this factory can create.
-
-    If no extra options are required it is allowed to return null like the default implementation does.
-    This is intended to be called from the RunConfiguration constructor, so passing a RunConfiguration
-    pointer makes no sense because that object is under construction at the time.
-*/
 
 /*!
     \fn RunConfigWidget *ProjectExplorer::IRunControlFactory::createConfigurationWidget(RunConfiguration *runConfiguration)
 
-    \brief Return a widget used to configure this runner. Ownership is transferred to the caller.
+    Returns a widget used to configure this runner. Ownership is transferred to
+    the caller.
 
-    Return 0 if @p runConfiguration is not suitable for RunControls from this factory, or no user-accessible
+    Returns 0 if @p \a runConfiguration is not suitable for RunControls from this
+    factory, or no user-accessible
     configuration is required.
 */
 
@@ -405,6 +406,16 @@ IRunControlFactory::~IRunControlFactory()
 {
 }
 
+/*!
+    Returns an IRunConfigurationAspect to carry options for RunControls this
+    factory can create.
+
+    If no extra options are required, it is allowed to return null like the
+    default implementation does. This function is intended to be called from the
+    RunConfiguration constructor, so passing a RunConfiguration pointer makes
+    no sense because that object is under construction at the time.
+*/
+
 IRunConfigurationAspect *IRunControlFactory::createRunConfigurationAspect(RunConfiguration *rc)
 {
     Q_UNUSED(rc);
@@ -416,18 +427,12 @@ IRunConfigurationAspect *IRunControlFactory::createRunConfigurationAspect(RunCon
     \brief The RunControl class instances represent one item that is run.
 */
 
-/*!
-    \fn bool ProjectExplorer::RunControl::promptToStop(bool *optionalPrompt = 0) const
-
-    \brief Prompt to stop. If 'optionalPrompt' is passed, a "Do not ask again"-
-    checkbox will show and the result will be returned in '*optionalPrompt'.
-*/
-
 /*!
     \fn QIcon ProjectExplorer::RunControl::icon() const
-    \brief Eeturns the icon to be shown in the Outputwindow.
+    Returns the icon to be shown in the Outputwindow.
 
-    TODO the icon differs currently only per "mode", so this is more flexible then it needs to be.
+    TODO the icon differs currently only per "mode", so this is more flexible
+    than it needs to be.
 */
 
 RunControl::RunControl(RunConfiguration *runConfiguration, RunMode mode)
@@ -487,6 +492,11 @@ void RunControl::setApplicationProcessHandle(const ProcessHandle &handle)
     }
 }
 
+/*!
+    Prompts to stop. If \a optionalPrompt is passed, a \gui {Do not ask again}
+    checkbox is displayed and the result is returned in \a *optionalPrompt.
+*/
+
 bool RunControl::promptToStop(bool *optionalPrompt) const
 {
     QTC_ASSERT(isRunning(), return true);
@@ -502,7 +512,8 @@ bool RunControl::promptToStop(bool *optionalPrompt) const
 }
 
 /*!
-    \brief Utility to prompt to terminate application with checkable box.
+    Prompts to terminate the application with the \gui {Do not ask again}
+    checkbox.
 */
 
 bool RunControl::showPromptToStopDialog(const QString &title,

src/plugins/projectexplorer/runconfigurationmodel.cpp

@@ -39,8 +39,8 @@ using namespace ProjectExplorer;
     \brief The RunConfigurationModel class provides a model to represent the
     run configurations of a target.
 
-    To be used in for the drop down of comboboxes.
+    To be used in the dropdown lists of comboboxes.
-    Does automatically adjust itself to added and removed RunConfigurations
+    Automatically adjusts itself to added and removed run configurations.
 */
 
 class RunConfigurationComparer

src/plugins/projectexplorer/session.cpp

@@ -70,8 +70,8 @@ using namespace ProjectExplorer::Internal;
      \brief The SessionManager class manages sessions.
 
      TODO the interface of this class is not really great.
-     The implementation suffers that all the functions from the
+     The implementation suffers from that all the functions from the
-     public interface just wrap around functions which do the actual work
+     public interface just wrap around functions which do the actual work.
      This could be improved.
 */
 
@@ -615,7 +615,7 @@ void SessionManager::removeProjects(QList<Project *> remove)
 }
 
 /*!
-    \brief Let other plugins store persistent values within the session file.
+    Lets other plugins store persistent values within the session file.
 */
 
 void SessionManager::setValue(const QString &name, const QVariant &value)
@@ -658,7 +658,7 @@ Utils::FileName SessionManager::sessionNameToFileName(const QString &session) co
 }
 
 /*!
-    \brief Just creates a new session (Does not actually create the file).
+    Creates \a session, but does not actually create the file.
 */
 
 bool SessionManager::createSession(const QString &session)
@@ -692,7 +692,7 @@ bool SessionManager::confirmSessionDelete(const QString &session)
 }
 
 /*!
-     \brief Deletes session name from session list and file from disk.
+     Deletes \a session name from session list and the file from disk.
 */
 bool SessionManager::deleteSession(const QString &session)
 {
@@ -801,7 +801,7 @@ void SessionManager::restoreEditors(const Utils::PersistentSettingsReader &reade
 }
 
 /*!
-     \brief Loads a session, takes a session name (not filename).
+     Loads a session, takes a session name (not filename).
 */
 void SessionManager::restoreProjects(const QStringList &fileList)
 {

src/plugins/projectexplorer/toolchain.cpp

@@ -152,9 +152,9 @@ bool ToolChain::operator == (const ToolChain &tc) const
 }
 
 /*!
-    \brief Used by the toolchainmanager to save user-generated tool chains.
+    Used by the tool chain manager to save user-generated tool chains.
 
-    Make sure to call this method when deriving!
+    Make sure to call this method when deriving.
 */
 
 QVariantMap ToolChain::toMap() const
@@ -181,9 +181,9 @@ void ToolChain::setAutoDetected(bool autodetect)
 }
 
 /*!
-    \brief Used by the toolchainmanager to load user-generated tool chains.
+    Used by the tool chain manager to load user-generated tool chains.
 
-    Make sure to call this method when deriving!
+    Make sure to call this method when deriving.
 */
 
 bool ToolChain::fromMap(const QVariantMap &data)
@@ -197,7 +197,7 @@ bool ToolChain::fromMap(const QVariantMap &data)
 }
 
 /*!
-    \brief Used by the toolchainkitinformation to validate the kit.
+    Used by the tool chain kit information to validate the kit.
 */
 
 QList<Task> ToolChain::validateKit(const Kit *) const
@@ -207,22 +207,25 @@ QList<Task> ToolChain::validateKit(const Kit *) const
 
 /*!
     \class ProjectExplorer::ToolChainFactory
-    \brief Creates toolchains from settings or autodetects them.
+    \brief The ToolChainFactory class creates tool chains from settings or
+    autodetects them.
 */
 
 /*!
     \fn QString ProjectExplorer::ToolChainFactory::displayName() const = 0
-    \brief Name used to display the name of the tool chain that will be created.
+    Contains the name used to display the name of the tool chain that will be
+    created.
 */
 
 /*!
     \fn QStringList ProjectExplorer::ToolChain::clangParserFlags(const QStringList &cxxflags) const = 0
-    \brief Converts toolchain-specific flags to list flags that tunes libclang parser
+    Converts tool chain specific flags to list flags that tune the libclang
+    parser.
 */
 
 /*!
     \fn bool ProjectExplorer::ToolChainFactory::canRestore(const QVariantMap &data)
-    \brief Used by the ToolChainManager to restore user-generated tool chains.
+    Used by the tool chain manager to restore user-generated tool chains.
 */
 
 QList<ToolChain *> ToolChainFactory::autoDetect()

src/plugins/projectexplorer/windebuginterface.cpp

@@ -41,7 +41,7 @@
 
     Emits output by process id.
 
-    OutputDebugString puts its data into a shared memory segment named
+    The \c OutputDebugString() function puts its data into a shared memory segment named
     \c DBWIN_BUFFER which can be accessed via file mapping.
 */