From: sbh <sergey.belash@opencascade.com>
Date: Fri, 23 Jan 2015 13:30:15 +0000 (+0300)
Subject: Corrections in the documentation of the Config package
X-Git-Tag: V_1.0.0~26^2~1
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=3828ae57873e6bda6ff760b85172bd439d1b4483;p=modules%2Fshaper.git

Corrections in the documentation of the Config package
---

diff --git a/src/Config/Config_AttributeMessage.cpp b/src/Config/Config_AttributeMessage.cpp
index cea94547e..3b37a27bd 100644
--- a/src/Config/Config_AttributeMessage.cpp
+++ b/src/Config/Config_AttributeMessage.cpp
@@ -1,8 +1,5 @@
 // Copyright (C) 2014-20xx CEA/DEN, EDF R&D
 
-/*
- *
- */
 #include "Config_AttributeMessage.h"
 
 Config_AttributeMessage::Config_AttributeMessage(const Events_ID theId, const void* theParent)
diff --git a/src/Config/Config_AttributeMessage.h b/src/Config/Config_AttributeMessage.h
index c93565758..160efa7e8 100644
--- a/src/Config/Config_AttributeMessage.h
+++ b/src/Config/Config_AttributeMessage.h
@@ -9,8 +9,9 @@
 
 #include <string>
 
-/*
- * Class to pass an attribute's (widget's) entry info extracted from xml file.
+/*!
+ * \class Config_AttributeMessage
+ * \brief Class to pass an attribute's (widget's) entry info extracted from xml file.
  * <widget id="tool_object" concealment="true" obligatory="0"/>
  */
 class Config_AttributeMessage : public Events_Message
diff --git a/src/Config/Config_Common.h b/src/Config/Config_Common.h
index a2cc78843..c1379efe6 100644
--- a/src/Config/Config_Common.h
+++ b/src/Config/Config_Common.h
@@ -28,12 +28,12 @@ typedef xmlDoc *xmlDocPtr;
 struct _xmlDoc;
 //<<
 
-/*
+/*!
  * Returns true if theNode is XML ELEMENT node (not a "text" node ie).
  */
 CONFIG_EXPORT bool isElementNode(xmlNodePtr theNode);
 
-/*
+/*!
  * Returns true if theNode is XML node with a given name.
 
  * Please note that this function should be called with NULL last argument.
@@ -43,12 +43,12 @@ CONFIG_EXPORT bool isElementNode(xmlNodePtr theNode);
  */
 CONFIG_EXPORT bool isNode(xmlNodePtr theNode, const char* theNodeName, ...);
 
-/*
+/*!
  * Checks is the given node is attribute (widget) node.
  */
 CONFIG_EXPORT bool isWidgetNode(xmlNodePtr theNode);
 
-/*
+/*!
  * Every xml node has child. Even if there is no explicit
  * child nodes libxml gives the "Text node" as child.
  *
@@ -57,7 +57,7 @@ CONFIG_EXPORT bool isWidgetNode(xmlNodePtr theNode);
  */
 CONFIG_EXPORT bool hasChild(xmlNodePtr theNode);
 
-/*
+/*!
  * Returns named property for an id node as std::string and the parameters of the node.
  */
 CONFIG_EXPORT bool getParametersInfo(xmlNodePtr theNode, std::string& outPropertyId,
@@ -76,12 +76,12 @@ CONFIG_EXPORT bool getParametersInfo(xmlNodePtr theNode, std::string& outPropert
  */
 CONFIG_EXPORT std::string library(const std::string& theLibName);
 
-/*
+/*!
  * Returns named property for a given node as std::string.
  */
 CONFIG_EXPORT std::string getProperty(xmlNodePtr theNode, const char* thePropName);
 
-/*
+/*!
  * Checks if the given XML node has the given attribute,
  * if yes - returns it's bool value, if no, or if the value can not
  * be converted to bool - returns theDefault value.
@@ -93,7 +93,7 @@ CONFIG_EXPORT bool getBooleanAttribute(xmlNodePtr theNode,
                                        const char* theAttributeName,
                                        bool theDefault);
 
-/*
+/*!
  * Returns normalized (lower case) version of string.
  * Should be used for case insensitive string matching.
  */
diff --git a/src/Config/Config_FeatureMessage.cpp b/src/Config/Config_FeatureMessage.cpp
index f5c77fb40..b925ab656 100644
--- a/src/Config/Config_FeatureMessage.cpp
+++ b/src/Config/Config_FeatureMessage.cpp
@@ -1,8 +1,5 @@
 // Copyright (C) 2014-20xx CEA/DEN, EDF R&D
 
-/*
- *
- */
 #include "Config_FeatureMessage.h"
 
 Config_FeatureMessage::Config_FeatureMessage(const Events_ID theId, const void* theParent)
diff --git a/src/Config/Config_FeatureMessage.h b/src/Config/Config_FeatureMessage.h
index 68bd94378..f890f44c3 100644
--- a/src/Config/Config_FeatureMessage.h
+++ b/src/Config/Config_FeatureMessage.h
@@ -8,8 +8,9 @@
 
 #include <string>
 
-/*
- * Class to pass a feature entry extracted from xml file.
+/*!
+ * \class Config_FeatureMessage
+ * \brief Class to pass a feature entry extracted from xml file.
  * Example of the feature entry:
  * <feature id="Part" text="New part" tooltip="Creates a new part" icon=":pictures/part_ico.png"/>
  */
diff --git a/src/Config/Config_FeatureReader.h b/src/Config/Config_FeatureReader.h
index eec7889b0..7986f3b59 100644
--- a/src/Config/Config_FeatureReader.h
+++ b/src/Config/Config_FeatureReader.h
@@ -20,24 +20,36 @@
 
 class Config_FeatureMessage;
 
+/*!
+ * \class Config_FeatureReader
+ * \brief Class to process feature's xml definition.
+ */
 class Config_FeatureReader : public Config_XMLReader
 {
  public:
-  Config_FeatureReader(const std::string& theXmlFile, const std::string& theLibraryName,
+  Config_FeatureReader(const std::string& theXmlFile,
+                       const std::string& theLibraryName,
                        const char* theEventGenerated = 0);
   virtual ~Config_FeatureReader();
-
+  /// Returns list of all features defined in reader's file
   std::list<std::string> features() const;
 
  protected:
-  void processNode(xmlNodePtr aNode);
-  bool processChildren(xmlNodePtr aNode);
+  /// Overloaded method. Defines how to process each node
+  virtual void processNode(xmlNodePtr aNode);
+  /// Overloaded method. Defines if the given node should be parsed recursively
+  virtual bool processChildren(xmlNodePtr aNode);
 
+  /// Fills feature message
   void fillFeature(xmlNodePtr theRoot, 
                    const std::shared_ptr<Config_FeatureMessage>& outFeatureMessage);
 
+  /// Stores an attribute in internal map for later use.
+  /// Key is "Node_Name:Node_Attribute" and value is getProperty(theNodeAttribute)
   void storeAttribute(xmlNodePtr theNode, const char* theNodeAttribute);
+  /// Restores an attribute from internal map.
   std::string restoreAttribute(xmlNodePtr theNode, const char* theNodeAttribute);
+  /// Restores an attribute from internal map.
   std::string restoreAttribute(const char* theNodeName, const char* theNodeAttribute);
 
  private:
diff --git a/src/Config/Config_ModuleReader.cpp b/src/Config/Config_ModuleReader.cpp
index 0b0245c5a..6acffa268 100644
--- a/src/Config/Config_ModuleReader.cpp
+++ b/src/Config/Config_ModuleReader.cpp
@@ -48,7 +48,7 @@ const std::map<std::string, std::string>& Config_ModuleReader::featuresInFiles()
   return myFeaturesInFiles;
 }
 
-/*
+/*!
  * Get module name from plugins.xml
  * (property "module")
  */
@@ -58,9 +58,6 @@ std::string Config_ModuleReader::getModuleName()
   return getProperty(aRoot, PLUGINS_MODULE);
 }
 
-/*
- *
- */
 void Config_ModuleReader::processNode(xmlNodePtr theNode)
 {
   if (isNode(theNode, NODE_PLUGIN, NULL)) {
diff --git a/src/Config/Config_ModuleReader.h b/src/Config/Config_ModuleReader.h
index cdfae0a43..911e5d813 100644
--- a/src/Config/Config_ModuleReader.h
+++ b/src/Config/Config_ModuleReader.h
@@ -18,6 +18,10 @@
 #include <set>
 #include <string>
 
+/*!
+ * \class Config_ModuleReader
+ * \brief Class to process plugins.xml - definition of plugins (scripts, libraries).
+ */
 class Config_ModuleReader : public Config_XMLReader
 {
   enum PluginType {
diff --git a/src/Config/Config_PointerMessage.h b/src/Config/Config_PointerMessage.h
index e745beb0e..4edb8c31e 100644
--- a/src/Config/Config_PointerMessage.h
+++ b/src/Config/Config_PointerMessage.h
@@ -13,8 +13,9 @@
 #include <Config_def.h>
 #include <Events_Message.h>
 
-/*
- * A general class to pass pointers over the event loop.
+/*!
+ * \class Config_PointerMessage
+ * \brief A general class to pass pointers over the event loop.
  */
 class CONFIG_EXPORT Config_PointerMessage : public Events_Message
 {
diff --git a/src/Config/Config_PropManager.h b/src/Config/Config_PropManager.h
index 4df2e5563..40e2f762a 100644
--- a/src/Config/Config_PropManager.h
+++ b/src/Config/Config_PropManager.h
@@ -14,7 +14,7 @@
 #include <string>
 #include <vector>
 
-//! Class wihich let to register properties
+//! Class which let to register properties
 class Config_PropManager
 {
  public:
diff --git a/src/Config/Config_SelectionFilterMessage.h b/src/Config/Config_SelectionFilterMessage.h
index d43b41382..fcc54a010 100644
--- a/src/Config/Config_SelectionFilterMessage.h
+++ b/src/Config/Config_SelectionFilterMessage.h
@@ -19,6 +19,10 @@
 /// Event ID that Selection Filter is loaded (comes with Config_SelectionFilterMessage)
 static const char * EVENT_SELFILTER_LOADED = "SelectionFilterLoaded";
 
+/*!
+ * \class Config_SelectionFilterMessage
+ * \brief Transmits info about selection filters on "SelectionFilterLoaded" event
+ */
 class Config_SelectionFilterMessage : public Events_Message
 {
   std::string mySelectionFilterId;
diff --git a/src/Config/Config_ValidatorMessage.h b/src/Config/Config_ValidatorMessage.h
index 186389193..d137097f9 100644
--- a/src/Config/Config_ValidatorMessage.h
+++ b/src/Config/Config_ValidatorMessage.h
@@ -19,6 +19,10 @@
 /// Event ID that Validator is loaded (comes with Config_ValidatorMessage)
 static const char * EVENT_VALIDATOR_LOADED = "ValidatorLoaded";
 
+/*!
+ * \class Config_ValidatorMessage
+ * \brief Transmits info about created validator on "ValidatorLoaded" event
+ */
 class Config_ValidatorMessage : public Events_Message
 {
   std::string myValidatorId;
diff --git a/src/Config/Config_WidgetAPI.h b/src/Config/Config_WidgetAPI.h
index ed58bb4f5..2c2cd9c71 100644
--- a/src/Config/Config_WidgetAPI.h
+++ b/src/Config/Config_WidgetAPI.h
@@ -27,6 +27,10 @@ typedef xmlDoc *xmlDocPtr;
 struct _xmlDoc;
 //<<
 
+/*!
+ * \class Config_WidgetAPI
+ * \brief Provides low-level API for WidgetFactory for reading xml definitions of widgets
+ */
 class CONFIG_EXPORT Config_WidgetAPI
 {
  public:
diff --git a/src/Config/Config_WidgetReader.h b/src/Config/Config_WidgetReader.h
index ab60f4278..783f2aa45 100644
--- a/src/Config/Config_WidgetReader.h
+++ b/src/Config/Config_WidgetReader.h
@@ -16,13 +16,19 @@
 #include <map>
 #include <string>
 
+/*!
+ * \class Config_WidgetReader
+ * \brief Class that dumps xml definitions of widgets for
+ * further processing in the WidgetFactory
+ */
 class Config_WidgetReader : public Config_XMLReader
 {
  public:
-  CONFIG_EXPORT Config_WidgetReader(const std::string& theXmlFile);CONFIG_EXPORT virtual ~Config_WidgetReader();
+  CONFIG_EXPORT Config_WidgetReader(const std::string& theXmlFile);
+  CONFIG_EXPORT virtual ~Config_WidgetReader();
 
-  CONFIG_EXPORT std::string featureWidgetCfg(const std::string& theFeatureName);CONFIG_EXPORT std::string featureDescription(
-      const std::string& theFeatureName);
+  CONFIG_EXPORT std::string featureWidgetCfg(const std::string& theFeatureName);
+  CONFIG_EXPORT std::string featureDescription(const std::string& theFeatureName);
 
  protected:
   void processNode(xmlNodePtr theNode);
diff --git a/src/Config/Config_XMLReader.cpp b/src/Config/Config_XMLReader.cpp
index 856e663be..a29eaab64 100644
--- a/src/Config/Config_XMLReader.cpp
+++ b/src/Config/Config_XMLReader.cpp
@@ -64,7 +64,7 @@ Config_XMLReader::~Config_XMLReader()
   xmlFreeDoc(myXmlDoc);
 }
 
-/*
+/*!
  * Read all nodes in associated xml file,
  * recursively if processChildren(xmlNode) is true for the xmlNode.
  * For each read node the processNode will be called.
@@ -75,7 +75,7 @@ void Config_XMLReader::readAll()
   readRecursively(aRoot);
 }
 
-/*
+/*!
  * Allows to customize reader's behavior for a node. Virtual.
  * The default impl does nothing. (In debug mode prints
  * some info)
@@ -96,7 +96,7 @@ void Config_XMLReader::processNode(xmlNodePtr theNode)
   }
 }
 
-/*
+/*!
  * Defines which nodes should be processed recursively. Virtual.
  * The default impl is to read all nodes.
  */
@@ -105,8 +105,9 @@ bool Config_XMLReader::processChildren(xmlNodePtr aNode)
   return true;
 }
 
-/*
- *
+/*!
+ * Returns xmlNodePtr to the root of reader's document
+ * or NULL if not found
  */
 xmlNodePtr Config_XMLReader::findRoot()
 {
@@ -129,7 +130,7 @@ xmlNodePtr Config_XMLReader::findRoot()
   return aRoot;
 }
 
-/*
+/*!
  * Calls processNode() for each child (for some - recursively)
  * of the given node.
  * \sa ReadAll()
@@ -151,7 +152,7 @@ void Config_XMLReader::readRecursively(xmlNodePtr theParent)
   }
 }
 
-/*
+/*!
  * void* -> xmlNodePtr
  */
 xmlNodePtr Config_XMLReader::node(void* theNode)
@@ -159,6 +160,9 @@ xmlNodePtr Config_XMLReader::node(void* theNode)
   return static_cast<xmlNodePtr>(theNode);
 }
 
+/*!
+ * Gets xml node name
+ */
 std::string Config_XMLReader::getNodeName(xmlNodePtr theNode)
 {
   std::string result = "";
@@ -169,6 +173,10 @@ std::string Config_XMLReader::getNodeName(xmlNodePtr theNode)
   return result;
 }
 
+/*!
+ * Retrieves all the necessary info from the validator node.
+ * Sends ValidatorLoaded event
+ */
 void Config_XMLReader::processValidator(xmlNodePtr theNode)
 {
   Events_ID aValidatoEvent = Events_Loop::eventByName(EVENT_VALIDATOR_LOADED);
@@ -190,6 +198,10 @@ void Config_XMLReader::processValidator(xmlNodePtr theNode)
   aEvLoop->send(aMessage);
 }
 
+/*!
+ * Retrieves all the necessary info from the SelectionFilter node.
+ * Sends SelectionFilterLoaded event
+ */
 void Config_XMLReader::processSelectionFilter(xmlNodePtr theNode)
 {
   Events_ID aFilterEvent = Events_Loop::eventByName(EVENT_SELFILTER_LOADED);
diff --git a/src/Config/Config_XMLReader.h b/src/Config/Config_XMLReader.h
index 119bd71c1..412af81a2 100644
--- a/src/Config/Config_XMLReader.h
+++ b/src/Config/Config_XMLReader.h
@@ -27,15 +27,16 @@ typedef xmlDoc *xmlDocPtr;
 struct _xmlDoc;
 //<<
 
-/*
- * Base class for all libxml readers. Provides high-level API
+/*!
+ * \class Config_XMLReader
+ * \brief Base class for all libxml readers. Provides high-level API
  * for all xml operations.
- *
- */
+*/
 class Config_XMLReader
 {
  public:
-  CONFIG_EXPORT Config_XMLReader(const std::string& theXmlFile);CONFIG_EXPORT virtual ~Config_XMLReader();
+  CONFIG_EXPORT Config_XMLReader(const std::string& theXmlFile);
+  CONFIG_EXPORT virtual ~Config_XMLReader();
 
   CONFIG_EXPORT void readAll();