Documentation: Add ProjectExplorer plugin..

Reformat existing documentation to qdoc.

1 files changed, 72 insertions, 56 deletions

diff --git a/src/plugins/projectexplorer/projectnodes.cpp b/src/plugins/projectexplorer/projectnodes.cpp
index 73808575db..dcf24a5a92 100644
--- a/src/plugins/projectexplorer/projectnodes.cpp
+++ b/src/plugins/projectexplorer/projectnodes.cpp
@@ -48,14 +48,20 @@
 using namespace ProjectExplorer;
 
 /*!
-  \class FileNode
+  \class ProjectExplorer::Node
 
-  Base class of all nodes in the node hierarchy.
+  \brief Base class of all nodes in the node hierarchy.
 
-  \see FileNode
-  \see FolderNode
-  \see ProjectNode
+  The nodes are arranged in a tree where leaves are FileNodes and non-leaves are FolderNodes
+  A Project is a special Folder that manages the files and normal folders underneath it.
+
+  The Watcher emits signals for structural changes in the hierarchy.
+  A Visitor can be used to traverse all Projects and other Folders.
+
+  \sa ProjectExplorer::FileNode, ProjectExplorer::FolderNode, ProjectExplorer::ProjectNode
+  \sa ProjectExplorer::NodesWatcher, ProjectExplorer::NodesVisitor
 */
+
 Node::Node(NodeType nodeType,
            const QString &filePath)
         : QObject(),
@@ -73,7 +79,7 @@ NodeType Node::nodeType() const
 }
 
 /*!
-  Project that owns & manages the node. It's the first project in list of ancestors.
+  \brief Project that owns & manages the node. It's the first project in list of ancestors.
   */
 ProjectNode *Node::projectNode() const
 {
@@ -81,7 +87,7 @@ ProjectNode *Node::projectNode() const
 }
 
 /*!
-  Parent in node hierarchy.
+  \brief Parent in node hierarchy.
   */
 FolderNode *Node::parentFolderNode() const
 {
@@ -89,7 +95,7 @@ FolderNode *Node::parentFolderNode() const
 }
 
 /*!
-  Path of file or folder in the filesystem the node represents.
+  \brief Path of file or folder in the filesystem the node represents.
   */
 QString Node::path() const
 {
@@ -117,12 +123,11 @@ void Node::setPath(const QString &path)
 }
 
 /*!
-  \class FileNode
+  \class ProjectExplorer::FileNode
 
-  In-memory presentation of a file. All FileNode's are leaf nodes.
+  \brief In-memory presentation of a file. All FileNode's are leaf nodes.
 
-  \see FolderNode
-  \see ProjectNode
+  \sa ProjectExplorer::FolderNode, ProjectExplorer::ProjectNode
 */
 
 FileNode::FileNode(const QString &filePath,
@@ -140,7 +145,7 @@ FileType FileNode::fileType() const
 }
 
 /*!
-  Returns true if the file is automatically generated by a compile step.
+  \brief Returns true if the file is automatically generated by a compile step.
   */
 bool FileNode::isGenerated() const
 {
@@ -148,12 +153,11 @@ bool FileNode::isGenerated() const
 }
 
 /*!
-  \class FolderNode
+  \class ProjectExplorer::FolderNode
 
   In-memory presentation of a folder. Note that the node itself + all children (files and folders) are "managed" by the owning project.
 
-  \see FileNode
-  \see ProjectNode
+  \sa ProjectExplorer::FileNode, ProjectExplorer::ProjectNode
 */
 FolderNode::FolderNode(const QString &folderPath)  :
     Node(FolderNodeType, folderPath),
@@ -167,20 +171,19 @@ FolderNode::~FolderNode()
     qDeleteAll(m_fileNodes);
 }
 
-/*
-  The display name that should be used in a view.
-
-
-  \see setFolderName()
+/*!
+    \brief The display name that should be used in a view.
+    \sa setFolderName()
  */
+
 QString FolderNode::displayName() const
 {
     return m_displayName;
 }
 
-/*
-  The icon that should be used in a view. Default is the directory icon (QStyle::S_PDirIcon).
-  \see setIcon()
+/*!
+  \brief The icon that should be used in a view. Default is the directory icon (QStyle::S_PDirIcon).
+  s\a setIcon()
  */
 QIcon FolderNode::icon() const
 {
@@ -218,17 +221,17 @@ void FolderNode::setIcon(const QIcon &icon)
 }
 
 /*!
-  \class ProjectNode
+  \class ProjectExplorer::ProjectNode
+
+  \brief In-memory presentation of a Project.
 
-  In-memory presentation of a Project.
   A concrete subclass must implement the "persistent" stuff
 
-  \see FileNode
-  \see FolderNode
+  \sa ProjectExplorer::FileNode, ProjectExplorer::FolderNode
 */
 
-/*
-  Creates uninitialized ProjectNode object.
+/*!
+  \brief Creates uninitialized ProjectNode object.
   */
 ProjectNode::ProjectNode(const QString &projectFilePath)
         : FolderNode(projectFilePath)
@@ -287,10 +290,12 @@ QList<NodesWatcher*> ProjectNode::watchers() const
     return m_watchers;
 }
 
-/*
-   Registers a watcher for the current project & all sub projects
+/*!
+   \brief Registers a watcher for the current project & all sub projects
+
    It does not take ownership of the watcher.
-   */
+*/
+
 void ProjectNode::registerWatcher(NodesWatcher *watcher)
 {
     if (!watcher)
@@ -302,8 +307,8 @@ void ProjectNode::registerWatcher(NodesWatcher *watcher)
         subProject->registerWatcher(watcher);
 }
 
-/*
-  Removes a watcher for the current project & all sub projects.
+/*!
+    \brief Removes a watcher for the current project & all sub projects.
 */
 void ProjectNode::unregisterWatcher(NodesWatcher *watcher)
 {
@@ -323,7 +328,7 @@ void ProjectNode::accept(NodesVisitor *visitor)
 }
 
 /*!
-  Adds project nodes to the hierarchy and emits the corresponding signals.
+  \brief Adds project nodes to the hierarchy and emits the corresponding signals.
   */
 void ProjectNode::addProjectNodes(const QList<ProjectNode*> &subProjects)
 {
@@ -355,9 +360,11 @@ void ProjectNode::addProjectNodes(const QList<ProjectNode*> &subProjects)
 }
 
 /*!
-  Remove project nodes from the hierarchy and emits the corresponding signals.
+  \brief Remove project nodes from the hierarchy and emits the corresponding signals.
+
   All objects in the argument list are deleted.
-  */
+*/
+
 void ProjectNode::removeProjectNodes(const QList<ProjectNode*> &subProjects)
 {
     if (!subProjects.isEmpty()) {
@@ -394,8 +401,8 @@ void ProjectNode::removeProjectNodes(const QList<ProjectNode*> &subProjects)
 }
 
 /*!
-  Adds folder nodes to the hierarchy and emits the corresponding signals.
-  */
+  \brief Adds folder nodes to the hierarchy and emits the corresponding signals.
+*/
 void ProjectNode::addFolderNodes(const QList<FolderNode*> &subFolders, FolderNode *parentFolder)
 {
     Q_ASSERT(parentFolder);
@@ -444,9 +451,10 @@ void ProjectNode::addFolderNodes(const QList<FolderNode*> &subFolders, FolderNod
 }
 
 /*!
-  Remove file nodes from the hierarchy and emits the corresponding signals.
+  \brief Remove file nodes from the hierarchy and emits the corresponding signals.
+
   All objects in the subFolders list are deleted.
-  */
+*/
 void ProjectNode::removeFolderNodes(const QList<FolderNode*> &subFolders,
                                    FolderNode *parentFolder)
 {
@@ -483,9 +491,11 @@ void ProjectNode::removeFolderNodes(const QList<FolderNode*> &subFolders,
 }
 
 /*!
-  Adds file nodes to the internal list and emits the corresponding signals.
+  \brief Adds file nodes to the internal list and emits the corresponding signals.
+
   This method should be called within an implementation of the public method addFiles.
-  */
+*/
+
 void ProjectNode::addFileNodes(const QList<FileNode*> &files, FolderNode *folder)
 {
     Q_ASSERT(folder);
@@ -530,10 +540,12 @@ void ProjectNode::addFileNodes(const QList<FileNode*> &files, FolderNode *folder
 }
 
 /*!
-  Remove file nodes from the internal list and emits the corresponding signals.
+  \brief Remove file nodes 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.
-  */
+*/
+
 void ProjectNode::removeFileNodes(const QList<FileNode*> &files, FolderNode *folder)
 {
     Q_ASSERT(folder);
@@ -573,14 +585,14 @@ void ProjectNode::watcherDestroyed(QObject *watcher)
 }
 
 /*!
-  Sort pointers to FileNodes
-  */
+  \brief Sort pointers to FileNodes
+*/
 bool ProjectNode::sortNodesByPath(Node *n1, Node *n2) {
     return n1->path() < n2->path();
 }
 
 /*!
-  \class SessionNode
+  \class ProjectExplorer::SessionNode
 */
 
 SessionNode::SessionNode(const QString &sessionPath, QObject *parentObject)
@@ -595,10 +607,11 @@ QList<NodesWatcher*> SessionNode::watchers() const
     return m_watchers;
 }
 
-/*
-   Registers a watcher for the complete session tree.
+/*!
+   \brief Registers a watcher for the complete session tree.
    It does not take ownership of the watcher.
 */
+
 void SessionNode::registerWatcher(NodesWatcher *watcher)
 {
     if (!watcher)
@@ -610,9 +623,10 @@ void SessionNode::registerWatcher(NodesWatcher *watcher)
         project->registerWatcher(watcher);
 }
 
-/*
-    Removes a watcher from the complete session tree
+/*!
+    \brief Removes a watcher from the complete session tree
 */
+
 void SessionNode::unregisterWatcher(NodesWatcher *watcher)
 {
     if (!watcher)
@@ -699,9 +713,9 @@ void SessionNode::watcherDestroyed(QObject *watcher)
 }
 
 /*!
-  \class NodesWatcher
+  \class ProjectExplorer::NodesWatcher
 
-  NodesWatcher let you keep track of changes in the tree.
+  \brief NodesWatcher lets you keep track of changes in the tree.
 
   Add a watcher by calling ProjectNode::registerWatcher() or
   SessionNode::registerWatcher(). Whenever the tree underneath the
@@ -711,8 +725,10 @@ void SessionNode::watcherDestroyed(QObject *watcher)
   by calling ProjectNode::unregisterWatcher and
   SessionNode::unregisterWatcher().
 
-  The NodesWatcher is similar to the Observer in the
+  The NodesWatcher is similar to the Observer in the  
   well-known Observer pattern (Booch et al).
+
+  \sa ProjectExplorer::Node
 */
 
 NodesWatcher::NodesWatcher(QObject *parent)