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/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.
-  This method should be called within an implementation of the public method removeFiles.
+  All objects in the \a files list are deleted.
+  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),
-  the corresponding signals of the NodesWatcher are emitted.
+  project node or session node changes (for example, nodes are added or removed),
+  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