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
-    YourBuildStep::init()
+    Reimplemented from BuildStep::init(). You need to call this from
+    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.
-    Does automatically adjust itself to added and removed BuildConfigurations
+    To be used in the dropdown lists of comboboxes.
+    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,
-    use it to retrieve any information that you need in run()
+    This function is run in the GUI thread. Use it to retrieve any information
+    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.
-    By default this function is NOT run in the gui thread. It runs in its
+    Reimplement this function. It is called when the target is built.
+    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
-    gui thread. Then the function should not block and instead the
+    By returning \c true from runInGuiThread(), this function is called in
+    the GUI thread. Then the function should not block and instead the
     finished() signal should be emitted.
-*/
-
-/*!
-    \fn BuildStepConfigWidget *ProjectExplorer::BuildStep::createConfigWidget()
 
-    Returns the Widget shown in the target settings dialog for this buildStep;
-    ownership is transferred to the caller.
+    \sa runInGuiThread()
 */
 
 /*!
-    \fn bool ProjectExplorer::BuildStep::immutable() const
+    \fn BuildStepConfigWidget *ProjectExplorer::BuildStep::createConfigWidget()
 
-    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.
+    Returns the Widget shown in the target settings dialog for this build step.
+    Ownership is transferred to the caller.
 */
 
 /*!
     \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
-    itself to added and removed DeployConfigurations
+    To be used in drop down lists of comboboxes. Automatically adjusts
+    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.
-   Parsers may have state (e.g. because they need to aggregate several lines into one task). This
+   Instructs a parser to flush its state.
+   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
-    should be called from init()
+    Sets the \a workingDirectory for the process for a build configuration.
+
+    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
-   or if the activeBuildConfiguration changes (including due to the active target changing).
+   A convenience signal emitted if activeBuildConfiguration emits
+   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()
-   or if the activeBuildConfiguration changes (including due to the active target changing).
+   A convenience signal emitted if activeBuildConfiguration emits
+   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)
 }