Added doxygen documentation for interfaces.

Change-Id: Idf5593a737a3da148b33c068c5d88bbb5eb82159
Reviewed-by: Bojan Petrovic <bojan85@gmail.com>

16 files changed, 174 insertions, 0 deletions

diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/activexreference.h b/src/plugins/vcprojectmanager/vcprojectmodel/activexreference.h
index 1ab0563ac7..002b6b8085 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/activexreference.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/activexreference.h
@@ -50,6 +50,10 @@ public:
     VcNodeWidget* createSettingsWidget();
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a ActiveXReference instance.
+     * \return A shared pointer to a newly created clone.
+     */
     virtual ActiveXReference::Ptr clone() const = 0;
 
     void addReferenceConfiguration(ReferenceConfiguration::Ptr refConfig);
@@ -69,6 +73,11 @@ protected:
     ActiveXReference();
     ActiveXReference(const ActiveXReference &ref);
     ActiveXReference& operator=(const ActiveXReference &ref);
+
+    /*!
+     * Called after instance of the ActiveXReference is created in order to initialize \b m_private member variable to
+     * a proper version of a ActiveXReference_Private implementation (2003, 2005 or 2008).
+     */
     virtual void init() = 0;
 
     ActiveXReference_Private::Ptr m_private;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/activexreference_private.h b/src/plugins/vcprojectmanager/vcprojectmodel/activexreference_private.h
index b2b891ab4f..fd7712ce17 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/activexreference_private.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/activexreference_private.h
@@ -68,7 +68,16 @@ protected:
     virtual void processReferenceConfig(const QDomNode &referenceConfig);
     virtual void processNodeAttributes(const QDomElement &element);
 
+    /*!
+     * Reimplement this to create a new reference configuration.
+     * \return A shared pointer to a newly created reference configuration.
+     */
     virtual ReferenceConfiguration::Ptr createReferenceConfiguration() const = 0;
+
+    /*!
+     * Implement in order to support creating a clone of a ActiveXReference_Private instance.
+     * \return A shared pointer to a newly created clone.
+     */
     virtual ActiveXReference_Private::Ptr clone() const = 0;
 
     QString m_controlGUID;  // required
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference.h b/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference.h
index 363e7bc75e..5f3746dd5f 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference.h
@@ -50,6 +50,10 @@ public:
     VcNodeWidget* createSettingsWidget();
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a assembly reference instance.
+     * \return A shared pointer to newly created assembly reference instance.
+     */
     virtual AssemblyReference::Ptr clone() const = 0;
 
     QString relativePath() const;
@@ -64,6 +68,11 @@ protected:
     AssemblyReference();
     AssemblyReference(const AssemblyReference &asmRef);
     AssemblyReference& operator=(const AssemblyReference &asmRef);
+
+    /*!
+     * Called after instance of the AssemblyReference is created in order to initialize \b m_private member variable to
+     * a proper version of a AssemblyReference_Private implementation (2003, 2005 or 2008).
+     */
     virtual void init() = 0;
 
     AssemblyReference_Private::Ptr m_private;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference_private.h b/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference_private.h
index f632010a22..8d031b47a7 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference_private.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/assemblyreference_private.h
@@ -62,7 +62,17 @@ protected:
 
     virtual void processNodeAttributes(const QDomElement &element);
     virtual void processReferenceConfig(const QDomNode &referenceConfig);
+
+    /*!
+     * Reimplement this to create a new reference configuration.
+     * \return A shared pointer to a newly created reference configuration.
+     */
     virtual ReferenceConfiguration::Ptr createReferenceConfiguration() const = 0;
+
+    /*!
+     * Implement in order to support creating a clone of a AssemblyReference_Private instance.
+     * \return A shared pointer to a newly created clone.
+     */
     virtual AssemblyReference_Private::Ptr clone() const = 0;
 
     QList<ReferenceConfiguration::Ptr > m_referenceConfigurations;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/configuration.h b/src/plugins/vcprojectmanager/vcprojectmodel/configuration.h
index c9cf0ba764..344074c5ed 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/configuration.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/configuration.h
@@ -52,6 +52,10 @@ public:
     virtual QString nodeWidgetName() const;
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a Configuration instance.
+     * \return A shared pointer to newly created Configuration instance.
+     */
     virtual Configuration::Ptr clone() const = 0;
 
     void addTool(Tool::Ptr tool);
@@ -75,6 +79,11 @@ protected:
     Configuration(const Configuration &config);
     Configuration& operator=(const Configuration &config);
     virtual void processToolNode(const QDomNode &toolNode);
+
+    /*!
+     * Called after instance of the Configuration is created in order to initialize \b m_private member variable to
+     * a proper version of a ConfigurationType implementation (2003, 2005 or 2008).
+     */
     virtual void init() = 0;
 
     ConfigurationType::Ptr m_configType;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/configurationtype.h b/src/plugins/vcprojectmanager/vcprojectmodel/configurationtype.h
index 9a8cc36f7f..7983098f35 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/configurationtype.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/configurationtype.h
@@ -67,6 +67,10 @@ public:
     void clearAttribute(const QString &attributeName);
     void removeAttribute(const QString &attributeName);
 
+    /*!
+     * Implement in order to support creating a clone of a configuration type instance.
+     * \return A shared pointer to newly created configuration type instance.
+     */
     virtual ConfigurationType::Ptr clone() const = 0;
 
 protected:
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/fileconfiguration.h b/src/plugins/vcprojectmanager/vcprojectmodel/fileconfiguration.h
index 0d21eed691..2876d79380 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/fileconfiguration.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/fileconfiguration.h
@@ -48,6 +48,10 @@ public:
     VcNodeWidget* createSettingsWidget();
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a FileConfiguration instance.
+     * \return A shared pointer to a newly created clone.
+     */
     virtual FileConfiguration::Ptr clone() const = 0;
 
     void addTool(Tool::Ptr tool);
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/files.h b/src/plugins/vcprojectmanager/vcprojectmodel/files.h
index 15497dfd27..b6302e7ed2 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/files.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/files.h
@@ -52,6 +52,11 @@ public:
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
     virtual bool isEmpty() const;
+
+    /*!
+     * Implement in order to support creating a clone of a Files instance.
+     * \return A shared pointer to newly created Files instance.
+     */
     virtual Files* clone() const = 0;
 
     void addFilter(Filter::Ptr newFilter);
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/files_private.h b/src/plugins/vcprojectmanager/vcprojectmodel/files_private.h
index 1ddeb4899d..1a7cd43e52 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/files_private.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/files_private.h
@@ -49,6 +49,10 @@ public:
     virtual void processNodeAttributes(const QDomElement &element);
     virtual QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a Files_Private instance.
+     * \return A shared pointer to newly created Files_Private instance.
+     */
     virtual QSharedPointer<Files_Private> clone() const = 0;
 
     void addFilter(Filter::Ptr newFilter);
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/ivcprojectnodemodel.h b/src/plugins/vcprojectmanager/vcprojectmodel/ivcprojectnodemodel.h
index 2c7d725355..d66a258402 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/ivcprojectnodemodel.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/ivcprojectnodemodel.h
@@ -43,9 +43,39 @@ public:
     IVcProjectXMLNode();
     virtual ~IVcProjectXMLNode();
 
+    /*!
+     * This member function is called when project file (vcproj) is processed.
+     * Note that before processing, the project file is loaded using XML DOM.
+     * After that, DOM document is processed recursively, node by node.
+     * When DOM node is processed a new project node is created.
+     * Attributes and children of that DOM node must be processed. That's when this member function is called.
+     * \param node represents current XML DOM node we are processing
+     */
     virtual void processNode(const QDomNode &node) = 0;
+
+    /*!
+     * This member function is called whenever XML DOM node element's attributes are processed.
+     * \param element is the current XML DOM elements which attributes we are processing.
+     */
     virtual void processNodeAttributes(const QDomElement &element) = 0;
+
+    /*!
+     * This member function is used to create settings widget for a node.
+     * For example, every Configuration project node creates it's own settings widget.
+     * This widget is created by calling createSettingsWidget() of every Tool project node present
+     * in that configuration and “appending” that widget as a child of a parent configuration widget.
+     * \return A pointer to a newly created settings widhget for a node.
+     */
     virtual VcNodeWidget* createSettingsWidget() = 0;
+
+    /*!
+     * This member function is called when project is creating it's own XML DOM  representation.
+     * Parent's implementation of toXMLDomNode is calling toXMLDomNode for every child.
+     * For example, we call this one in VcProjectDocument::saveToFile(const QString &filePath) member
+     * function's implementation in order to create project's XML DOM document which is used to save a project to a file.
+     * \param domXMLDocument is the parent XML DOM document to which newly created XML DOM node will belong to.
+     * \return A XML DOM node that represents this project node.
+     */
     virtual QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const = 0;
 };
 
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/projectreference.h b/src/plugins/vcprojectmanager/vcprojectmodel/projectreference.h
index 6d91132aa6..b1d05bd5bc 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/projectreference.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/projectreference.h
@@ -51,6 +51,10 @@ public:
     VcNodeWidget* createSettingsWidget();
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a ProjectReference instance.
+     * \return A shared pointer to newly created ProjectReference instance.
+     */
     virtual ProjectReference::Ptr clone() const = 0;
 
     QString name() const;
@@ -67,6 +71,11 @@ protected:
     ProjectReference();
     ProjectReference(const ProjectReference &projRef);
     ProjectReference& operator=(const ProjectReference &projRef);
+
+    /*!
+     * Called after instance of the ProjectReference is created in order to initialize \b m_private member variable to
+     * a proper version of a ProjectReference_Private implementation (2003, 2005 or 2008).
+     */
     virtual void init() = 0;
 
     ProjectReference_Private::Ptr m_private;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/projectreference_private.h b/src/plugins/vcprojectmanager/vcprojectmodel/projectreference_private.h
index 77f792bd68..35ab1bcff4 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/projectreference_private.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/projectreference_private.h
@@ -47,6 +47,10 @@ public:
     virtual void processNode(const QDomNode &node);
     virtual QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone of a ProjectReference_Private instance.
+     * \return A shared pointer to newly created ProjectReference_Private instance.
+     */
     virtual ProjectReference_Private::Ptr clone() const = 0;
 
     QString name() const;
@@ -65,6 +69,11 @@ protected:
     ProjectReference_Private& operator=(const ProjectReference_Private &projRef_p);
     virtual void processReferenceConfig(const QDomNode &referenceConfig);
     virtual void processNodeAttributes(const QDomElement &element);
+
+    /*!
+     * Reimplement this to create a new reference configuration.
+     * \return A shared pointer to a newly created reference configuration.
+     */
     virtual ReferenceConfiguration::Ptr createReferenceConfiguration() const = 0;
 
     QList<ReferenceConfiguration::Ptr > m_referenceConfigurations;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/referenceconfiguration.h b/src/plugins/vcprojectmanager/vcprojectmodel/referenceconfiguration.h
index f8ba3651df..befee1660f 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/referenceconfiguration.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/referenceconfiguration.h
@@ -50,6 +50,10 @@ public:
     VcNodeWidget* createSettingsWidget();
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
 
+    /*!
+     * Implement in order to support creating a clone to a ReferenceConfiguration.
+     * \return A shared pointer to newly created ReferenceConfiguration instance.
+     */
     virtual ReferenceConfiguration::Ptr clone() const = 0;
 
     void addTool(Tool::Ptr tool);
@@ -69,6 +73,11 @@ protected:
     ReferenceConfiguration(const ReferenceConfiguration &refConf);
     ReferenceConfiguration& operator=(const ReferenceConfiguration &refConf);
     virtual void processToolNode(const QDomNode &toolNode);
+
+    /*!
+     * Called after instance of the ReferenceConfiguration is created in order to initialize \b m_private member variable to
+     * a proper version of a ConfigurationType implementation (2003, 2005 or 2008).
+     */
     virtual void init() = 0;
 
     ConfigurationType::Ptr m_configType;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/tools/tool.h b/src/plugins/vcprojectmanager/vcprojectmodel/tools/tool.h
index abe2547eca..4375313f16 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/tools/tool.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/tools/tool.h
@@ -61,6 +61,10 @@ public:
     void removeAttribute(const QString &attributeName);
     bool containsAttribute(const QString &attributeName) const;
 
+    /*!
+     * Implement this member function to return a clone of a tool
+     * \return A shared pointer to a cloned tool object.
+     */
     virtual Tool::Ptr clone() const = 0;
 protected:
     bool readBooleanAttribute(const QString &attributeName, bool defaultBoolValue) const;
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/vcdocprojectnodes.h b/src/plugins/vcprojectmanager/vcprojectmodel/vcdocprojectnodes.h
index aafcefe38d..2dfe3e8699 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/vcdocprojectnodes.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/vcdocprojectnodes.h
@@ -80,13 +80,44 @@ public:
 
     VcContainerType vcContainerType() const;
 
+    /*!
+     * Implement this member function if you want to add a new VcFileNode to a VcContainerNode based on a full path to a file that
+     * should be added.
+     * \param filePath is a full path to a file for which node should be created.
+     */
     virtual void addFileNode(const QString &filePath) = 0;
+
+    /*!
+     * Implement this member function if you want to support appending of a VcFileNode node to a VcContainerNode.
+     * \param fileNode is a pointer to a VcFileNode that should be append as a child of this VcContainerNode.
+     * \return \b true if file node is successfully append as a child of VcContainerNode. Otherwise it returns \b false.
+     */
     virtual bool appendFileNode(VcFileNode *fileNode) = 0;
 
+    /*!
+     * Implement this member function if you want to add a new VcFilterNode to a VcContainerNode based on a name of a filter.
+     * should be added.
+     * \param name is a name of the filter.
+     */
     virtual void addFilterNode(const QString &name) = 0;
+
+    /*!
+     * Implement this member function if you want to support appending of a VcFilterNode node to a VcContainerNode.
+     * \param filterNode is a pointer to a VcFilterNode that should be append as a child of this VcContainerNode.
+     * \return \b true if file node is successfully append as a child of VcContainerNode. Otherwise it returns \b false.
+     */
     virtual bool appendFilterNode(VcFilterNode *folderNode) = 0;
 
+    /*!
+     * Implement this member function if you want to remove a filter node from VcContainerNode.
+     * \param filterNode is a pointer to a VcFilterNode that will be removed.
+     */
     virtual void removeFilterNode(VcFilterNode *filterNode) = 0;
+
+    /*!
+     * Implement this member function if you want to remove a file node from VcContainerNode.
+     * \param fileNode is a pointer to a VcFileNode that will be removed.
+     */
     virtual void removeFileNode(VcFileNode *fileNode) = 0;
 
     VcFileNode* findFileNode(const QString &filePath);
diff --git a/src/plugins/vcprojectmanager/vcprojectmodel/vcprojectdocument.h b/src/plugins/vcprojectmanager/vcprojectmodel/vcprojectdocument.h
index f866cf7b8d..401414366a 100644
--- a/src/plugins/vcprojectmanager/vcprojectmodel/vcprojectdocument.h
+++ b/src/plugins/vcprojectmanager/vcprojectmodel/vcprojectdocument.h
@@ -60,7 +60,21 @@ public:
     VcDocConstants::DocumentVersion documentVersion() const;
     QString filePath() const;
     void allProjectFiles(QStringList &sl) const;
+
+    /*!
+     * Implementation should return a minimal version of MS Build tool that is required to build a project.
+     * For example VS 2008 project can be compiled with MS Build 3.0 and 3.5.
+     * So the minimal MS Build version for VS 2008 projects is 3.0
+     * \return A minimal supported Ms Build version that is required to compile a project.
+     */
     virtual MsBuildInformation::MsBuildVersion minSupportedMsBuildVersion() const = 0;
+
+    /*!
+     * Implementation should return a max version of MS Build tool that can be used to build a project.
+     * For example VS 2008 project can be compiled with MS Build 3.0 and 3.5.
+     * So the maximum MS Build version for VS 2008 projects is 3.5
+     * \return
+     */
     virtual MsBuildInformation::MsBuildVersion maxSupportedMsBuildVersion() const = 0;
 
     // helper function, used to create a relative path to a file, path is relative to a project's file path
@@ -81,6 +95,11 @@ protected:
     virtual void processVisualStudioNode(const QDomElement &vsNode);
     QDomNode toXMLDomNode(QDomDocument &domXMLDocument) const;
     virtual QDomElement toVcDocumentElement(QDomDocument &domXMLDocument) const;
+
+    /*!
+     * Called to initialize VcProjectDocument after instance is created.
+     * This is the place in which objects that represent Configurations, References, Globals etc. should be created.
+     */
     virtual void init() = 0;
 
     void parseProcessingInstruction(const QDomProcessingInstruction &processingInstruction);