From 077ca08b7937cca4b459b8a3b7edd51bafc770d2 Mon Sep 17 00:00:00 2001
From: enk <enk@opencascade.com>
Date: Fri, 15 Jul 2005 11:06:29 +0000
Subject: [PATCH] Update comments

---
 src/CAM/CAM_Application.cxx | 79 +++++++++++++++++++++++++++++++++++++
 src/CAM/CAM_Application.h   |  3 ++
 src/CAM/CAM_DataModel.cxx   | 17 +++++++-
 src/CAM/CAM_DataModel.h     | 17 ++++----
 src/CAM/CAM_DataObject.cxx  |  9 +++++
 src/CAM/CAM_Module.cxx      | 14 +------
 src/CAM/CAM_Module.h        | 15 +++++++
 src/CAM/CAM_RootObject.cxx  | 14 +++++++
 src/CAM/CAM_Study.cxx       | 32 +++++++++++++++
 src/CAM/CAM_Study.h         |  4 ++
 10 files changed, 182 insertions(+), 22 deletions(-)

diff --git a/src/CAM/CAM_Application.cxx b/src/CAM/CAM_Application.cxx
index d13c53ef5..4f276dfa8 100755
--- a/src/CAM/CAM_Application.cxx
+++ b/src/CAM/CAM_Application.cxx
@@ -19,11 +19,15 @@
 #include <dlfcn.h>
 #endif
 
+/*!Create new instance of CAM_Application*/
 extern "C" CAM_EXPORT SUIT_Application* createApplication()
 {
   return new CAM_Application();
 }
 
+/*!Constructor. read module list.
+ * \param autoLoad - auto load flag.
+ */
 CAM_Application::CAM_Application( const bool autoLoad )
 : STD_Application(),
 myModule( 0 ),
@@ -32,10 +36,14 @@ myAutoLoad( autoLoad )
   readModuleList();
 }
 
+/*!Destructor. Do nothing.*/
 CAM_Application::~CAM_Application()
 {
 }
 
+/*! Load modules, if \a myAutoLoad flag is true.\n
+ * Start application - call start() method from parent class.
+ */
 void CAM_Application::start()
 {
   if ( myAutoLoad )
@@ -44,11 +52,17 @@ void CAM_Application::start()
   STD_Application::start();
 }
 
+/*!Get active module.
+ * \retval CAM_Module - active module.
+ */
 CAM_Module* CAM_Application::activeModule() const
 {
   return myModule;
 }
 
+/*!Get module with name \a modName from modules list.
+ * \retval CAM_Module pointer - module.
+ */
 CAM_Module* CAM_Application::module(  const QString& modName ) const
 {
   CAM_Module* mod = 0;
@@ -58,11 +72,15 @@ CAM_Module* CAM_Application::module(  const QString& modName ) const
   return mod;
 }
 
+/*!Gets modules iterator.*/
 CAM_Application::ModuleListIterator CAM_Application::modules() const
 {
   return ModuleListIterator( myModules );
 }
 
+/*!Gets modules list.
+ * \param out - output list of modules.
+ */
 void CAM_Application::modules( CAM_Application::ModuleList& out ) const
 {
   out.setAutoDelete( false );
@@ -72,6 +90,12 @@ void CAM_Application::modules( CAM_Application::ModuleList& out ) const
     out.append( it.current() );
 }
 
+/*!Gets list of names for modules.\n
+ * Get loaded modules names, if \a loaded is true, else \n
+ * get names from information list.
+ * \param lst - output list of names.
+ * \param loaded - boolean flag.
+ */
 void CAM_Application::modules( QStringList& lst, const bool loaded ) const
 {
   lst.clear();
@@ -84,6 +108,9 @@ void CAM_Application::modules( QStringList& lst, const bool loaded ) const
       lst.append( (*it).title );
 }
 
+/*!Adding module \a mod to list.
+ *\param mod - module.
+ */
 void CAM_Application::addModule( CAM_Module* mod )
 {
   if ( !mod || myModules.contains( mod ) )
@@ -122,6 +149,9 @@ void CAM_Application::addModule( CAM_Module* mod )
   moduleAdded( mod );
 }
 
+/*!Load modules from information list.
+ * \warning If some of modules not loaded, error message appear on desktop.
+ */
 void CAM_Application::loadModules()
 {
   for ( ModuleInfoList::const_iterator it = myInfoList.begin(); it != myInfoList.end(); ++it )
@@ -135,6 +165,12 @@ void CAM_Application::loadModules()
   }
 }
 
+/*!Load module with name \a modName.
+ *\param modName - module name for loading.
+ *\warning If information list is empty.
+ *\warning If module library (for module with \a modName) is empty.
+ *\warning If module library is not loaded.
+ */
 CAM_Module* CAM_Application::loadModule( const QString& modName )
 {
   if ( myInfoList.isEmpty() )
@@ -200,6 +236,12 @@ CAM_Module* CAM_Application::loadModule( const QString& modName )
   return module;
 }
 
+/**@name Activate module group.*/
+//@{
+/*!Activate module with name \a modName.
+ *\param modName - module name.
+ *\ratval true, if module loaded and activated successful, else false.
+ */
 bool CAM_Application::activateModule( const QString& modName )
 {
   if ( !modName.isEmpty() && !activeStudy() )
@@ -224,6 +266,11 @@ bool CAM_Application::activateModule( const QString& modName )
   return res;
 }
 
+/*!Activate module \a mod
+ *\param mod - module for activation.
+ *\retval true - if all sucessful.
+ *\warning Error message if module not activated in active study.
+ */
 bool CAM_Application::activateModule( CAM_Module* mod )
 {
   if ( mod && !activeStudy() )
@@ -271,12 +318,17 @@ bool CAM_Application::activateModule( CAM_Module* mod )
 
   return true;
 }
+//@}
 
+/*!Create new study for current application.
+ *\retval study pointer.
+ */
 SUIT_Study* CAM_Application::createNewStudy() 
 { 
   return new CAM_Study( this );
 }
 
+/*!Update commands status for parent class and for current class(if module is active)*/
 void CAM_Application::updateCommandsStatus()
 {
   STD_Application::updateCommandsStatus();
@@ -285,17 +337,24 @@ void CAM_Application::updateCommandsStatus()
     activeModule()->updateCommandsStatus();
 }
 
+/*!Close all modules in study \a theDoc.
+ *\param theDoc - study
+ */
 void CAM_Application::beforeCloseDoc( SUIT_Study* theDoc )
 {
   for ( ModuleListIterator it( myModules ); it.current(); ++it )
     it.current()->studyClosed( theDoc );
 }
 
+/*!Sets active study for parent class.
+ *\param study - study.
+ */
 void CAM_Application::setActiveStudy( SUIT_Study* study )
 {
   STD_Application::setActiveStudy( study );
 }
 
+/*!Do nothing.*/
 void CAM_Application::moduleAdded( CAM_Module* mod )
 {
 //  CAM_Study* study = dynamic_cast<CAM_Study*>( activeStudy() );
@@ -305,6 +364,10 @@ void CAM_Application::moduleAdded( CAM_Module* mod )
 //  study->insertDataModel( mod->dataModel() );
 }
 
+/*!Gets module name by title \a title
+ *\param title - title name
+ *\retval QString module name.
+ */
 QString CAM_Application::moduleName( const QString& title ) const
 {
   QString res;
@@ -316,6 +379,10 @@ QString CAM_Application::moduleName( const QString& title ) const
   return res;
 }
 
+/*!Gets module title by module name \a name
+ *\param name - module name
+ *\retval QString module title.
+ */
 QString CAM_Application::moduleTitle( const QString& name ) const
 {
   QString res;
@@ -327,6 +394,11 @@ QString CAM_Application::moduleTitle( const QString& name ) const
   return res;
 }
 
+/*!Get library name for module with title \a title.
+ *\param title - module title name.
+ *\param full  - boolean flag (if true - return full library name, else internal name)
+ *\retval QString - library name.
+ */
 QString CAM_Application::moduleLibrary( const QString& title, const bool full ) const
 {
   QString res;
@@ -340,6 +412,7 @@ QString CAM_Application::moduleLibrary( const QString& title, const bool full )
   return res;
 }
 
+/*!Read modules list*/
 void CAM_Application::readModuleList()
 {
   if ( !myInfoList.isEmpty() )
@@ -390,6 +463,11 @@ void CAM_Application::readModuleList()
     SUIT_MessageBox::error1( 0, tr( "Error" ), tr( "Can not load modules configuration file " ), tr( "Ok" ) );
 }
 
+/*!Add common items for popup menu ( if they are exist )
+ *\param type - type of popup menu
+ *\param thePopup - popup menu
+ *\param title - title of popup menu
+ */
 void CAM_Application::contextMenuPopup( const QString& type, QPopupMenu* thePopup, QString& title )
 {
   // to do : add common items for popup menu ( if they are exist )
@@ -397,6 +475,7 @@ void CAM_Application::contextMenuPopup( const QString& type, QPopupMenu* thePopu
     activeModule()->contextMenuPopup( type, thePopup, title );
 }
 
+/*!Create empty study.*/
 void CAM_Application::createEmptyStudy()
 {
   SUIT_Study* study = activeStudy();
diff --git a/src/CAM/CAM_Application.h b/src/CAM/CAM_Application.h
index 0ec5fd187..a485688b1 100755
--- a/src/CAM/CAM_Application.h
+++ b/src/CAM/CAM_Application.h
@@ -30,9 +30,12 @@ public:
   CAM_Module*         activeModule() const;
   CAM_Module*         module(  const QString& ) const;
 
+  /** @name Modules lists.*/
+  //@{
   ModuleListIterator  modules() const;
   void                modules( ModuleList& ) const;
   void                modules( QStringList&, const bool loaded = true ) const;
+  //@}
 
   virtual void        addModule( CAM_Module* );
 
diff --git a/src/CAM/CAM_DataModel.cxx b/src/CAM/CAM_DataModel.cxx
index a97546a67..a2f46aa72 100755
--- a/src/CAM/CAM_DataModel.cxx
+++ b/src/CAM/CAM_DataModel.cxx
@@ -3,27 +3,36 @@
 #include "CAM_Module.h"
 #include "CAM_RootObject.h"
 
+/*!Constructor. Initialise module by \a module.*/
 CAM_DataModel::CAM_DataModel( CAM_Module* module )
 : myRoot( 0 ),
 myModule( module )
 {
 }
 
+/*!Destructor. Do nothing.*/
 CAM_DataModel::~CAM_DataModel()
 {
 }
 
 void CAM_DataModel::initialize()
 {
-  // Default implementation, does nothing.
-  // Can be used for creation of root object.
+  //! Default implementation, does nothing.\n
+  //! Can be used for creation of root object.
 }
 
+/*!Get root object.
+ *\retval CAM_DataObject pointer - root object.
+ */
 CAM_DataObject* CAM_DataModel::root() const
 {
   return myRoot;
 }
 
+/*!Sets root object to \a newRoot.\n
+ *Emit root changed, if it was.
+ *\param newRoot - new root object
+ */
 void CAM_DataModel::setRoot( const CAM_DataObject* newRoot )
 {
   if ( myRoot == newRoot )
@@ -40,11 +49,15 @@ void CAM_DataModel::setRoot( const CAM_DataObject* newRoot )
   emit rootChanged( this );
 }
 
+/*!Gets module.
+ *\retval CAM_Module pointer - module.
+ */
 CAM_Module* CAM_DataModel::module() const
 {
   return myModule;
 }
 
+/*!Nullify root, if \a obj equal root.*/
 void CAM_DataModel::onDestroyed( SUIT_DataObject* obj )
 {
   if ( myRoot == obj )
diff --git a/src/CAM/CAM_DataModel.h b/src/CAM/CAM_DataModel.h
index 5fbf9709d..d55465bee 100755
--- a/src/CAM/CAM_DataModel.h
+++ b/src/CAM/CAM_DataModel.h
@@ -23,20 +23,23 @@ public:
   CAM_DataObject*  root() const;
   CAM_Module*      module() const;
 
-  // These methods should be redefined in successors.
-  virtual bool     open( const QString&, CAM_Study* ) { return true; }
+  /** @name These methods should be redefined in successors.*/
+  //@{
+  virtual bool     open( const QString&, CAM_Study* ) { return true; }//!< return true
   virtual bool     save() { return true; };
   virtual bool     saveAs( const QString&, CAM_Study* ) { return true; };
   virtual bool     close() { return true; };
   virtual bool     create( CAM_Study* ) { return true; }
+  //@}
 
 protected:
+  /*! setRoot() should be used to specify custom root object instance.\n
+   * Such an object can be created in several ways, depending on application or module needs:\n
+   * \li by initialize()
+   * \li while the model is being loaded
+   * \li when the model is updated and becomes non-empty 
+   */
   virtual void     setRoot( const CAM_DataObject* );
-  // setRoot() should be used to specify custom root object instance.
-  // Such an object can be created in several ways, depending on application or module needs:
-  // - by initialize() 
-  // - while the model is being loaded 
-  // - when the model is updated and becomes non-empty
 
 private slots:
   void             onDestroyed( SUIT_DataObject* );
diff --git a/src/CAM/CAM_DataObject.cxx b/src/CAM/CAM_DataObject.cxx
index 96a938b84..c2069fdff 100755
--- a/src/CAM/CAM_DataObject.cxx
+++ b/src/CAM/CAM_DataObject.cxx
@@ -3,15 +3,20 @@
 #include "CAM_Module.h"
 #include "CAM_DataModel.h"
 
+/*!Constructor. Sets parent object.*/
 CAM_DataObject::CAM_DataObject( SUIT_DataObject* parent )
 : SUIT_DataObject( parent )
 {
 }
 
+/*!Destructor.Do nothing*/
 CAM_DataObject::~CAM_DataObject()
 {
 }
 
+/*!Get module.
+ *\retval const CAM_Module pointer - module
+ */
 CAM_Module* CAM_DataObject::module() const
 { 
   CAM_Module* mod = 0;
@@ -23,6 +28,10 @@ CAM_Module* CAM_DataObject::module() const
   return mod;
 }
 
+/*!Get data model.
+ *Return 0 - if no parent obbject.
+ *\retval const CAM_DataModel pointer - data model
+ */
 CAM_DataModel* CAM_DataObject::dataModel() const
 {
   CAM_DataObject* parentObj = dynamic_cast<CAM_DataObject*>( parent() );
diff --git a/src/CAM/CAM_Module.cxx b/src/CAM/CAM_Module.cxx
index 26e55f7fd..81ef5e1d0 100755
--- a/src/CAM/CAM_Module.cxx
+++ b/src/CAM/CAM_Module.cxx
@@ -175,10 +175,8 @@ QtxActionToolMgr* CAM_Module::toolMgr() const
   return mgr;
 }
 
-/** @name Create tool methods.*/
-//@{
 /*! Create tool bar with name \a name, if it was't created before.
- * \retval -1 - if tool bar was already created.
+ * \retval -1 - if tool manager was't be created.
  */
 int CAM_Module::createTool( const QString& name )
 {
@@ -226,10 +224,7 @@ int CAM_Module::createTool( const int id, const QString& tBar, const int idx )
   int intId = toolMgr()->insert( action( id ), tBar, idx );
   return intId != -1 ? id : -1;
 }
-//@}
 
-/** @name Create menu methods.*/
-//@{
 int CAM_Module::createMenu( const QString& subMenu, const int menu,
                             const int id, const int group, const int index )
 {
@@ -285,10 +280,7 @@ int CAM_Module::createMenu( const int id, const QString& menu, const int group,
   int intId = menuMgr()->insert( action( id ), menu, group, index );
   return intId != -1 ? id : -1;
 }
-//@}
 
-/** @name Set Menu Shown*/
-//@{
 /*!Sets menus shown to \a on floag.
  *\param on - flag.
  */
@@ -331,10 +323,7 @@ void CAM_Module::setMenuShown( const int id, const bool on )
 {
   setMenuShown( action( id ), on );
 }
-//@}
 
-/** @name Set Tool Shown*/
-//@{
 /*!Set tools shown to \a on flag.
  *\param on - boolean flag.
  */
@@ -377,7 +366,6 @@ void CAM_Module::setToolShown( const int id, const bool on )
 {
   setToolShown( action( id ), on );
 }
-//@}
 
 /*! Return action by id. 
  * \param id - id of action.
diff --git a/src/CAM/CAM_Module.h b/src/CAM/CAM_Module.h
index 97f43e31f..85d1b347a 100755
--- a/src/CAM/CAM_Module.h
+++ b/src/CAM/CAM_Module.h
@@ -54,31 +54,46 @@ protected:
   QtxActionMenuMgr*      menuMgr() const;
   QtxActionToolMgr*      toolMgr() const;
 
+  /** @name Create tool methods.*/
+  //@{
   int                    createTool( const QString& );
   int                    createTool( const int, const int, const int = -1 );
   int                    createTool( const int, const QString&, const int = -1 );
   int                    createTool( QAction*, const int, const int = -1, const int = -1 );
   int                    createTool( QAction*, const QString&, const int = -1, const int = -1 );
+  //@}
 
+  /** @name Create menu methods.*/
+  //@{
   int                    createMenu( const QString&, const int, const int = -1, const int = -1, const int = -1 );
   int                    createMenu( const QString&, const QString&, const int = -1, const int = -1, const int = -1 );
   int                    createMenu( const int, const int, const int = -1, const int = -1 );
   int                    createMenu( const int, const QString&, const int = -1, const int = -1 );
   int                    createMenu( QAction*, const int, const int = -1, const int = -1, const int = -1 );
   int                    createMenu( QAction*, const QString&, const int = -1, const int = -1, const int = -1 );
+  //@}
 
+  /** @name Set Menu Shown*/
+  //@{
   void                   setMenuShown( const bool );
   void                   setMenuShown( QAction*, const bool );
   void                   setMenuShown( const int, const bool );
+  //@}
 
+  /** @name Set Tool Shown*/
+  //@{
   void                   setToolShown( const bool );
   void                   setToolShown( QAction*, const bool );
   void                   setToolShown( const int, const bool );
+  //@}
 
   static QAction*        separator();
 
+  /**Action ids methods.*/
+  //@{
   QAction*               action( const int ) const;
   int                    actionId( const QAction* ) const;
+  //@}
 
   int                    registerAction( const int, QAction* );
   QAction*               createAction( const int, const QString&, const QIconSet&, const QString&,
diff --git a/src/CAM/CAM_RootObject.cxx b/src/CAM/CAM_RootObject.cxx
index 807fe6cd6..e24827167 100755
--- a/src/CAM/CAM_RootObject.cxx
+++ b/src/CAM/CAM_RootObject.cxx
@@ -2,27 +2,41 @@
 
 #include "CAM_DataModel.h"
 
+/*!Constructor. Initialize by \a parent.
+ * Set data model to 0.
+ */
 CAM_RootObject::CAM_RootObject( SUIT_DataObject* parent )
 : CAM_DataObject( parent ),
 myDataModel( 0 )
 {
 }
 
+/*!Constructor. Initialize by \a parent and \a data - data object
+ *\param data - data object
+ *\param parent - parent data object
+ */
 CAM_RootObject::CAM_RootObject( CAM_DataModel* data, SUIT_DataObject* parent )
 : CAM_DataObject( parent ),
 myDataModel( data )
 {
 }
 
+/*!Destructor. Do nothing.*/
 CAM_RootObject::~CAM_RootObject()
 {
 }
 
+/*!Get data model
+ *\retval const CAM_DataModel pointer to data model.
+ */
 CAM_DataModel* CAM_RootObject::dataModel() const
 {
   return myDataModel;
 }
 
+/*!Set data model.
+ *\param dm - data model to set.
+ */
 void CAM_RootObject::setDataModel( CAM_DataModel* dm )
 {
   myDataModel = dm;
diff --git a/src/CAM/CAM_Study.cxx b/src/CAM/CAM_Study.cxx
index 95a566fbb..421bb457a 100755
--- a/src/CAM/CAM_Study.cxx
+++ b/src/CAM/CAM_Study.cxx
@@ -5,15 +5,20 @@
 #include "CAM_RootObject.h"
 #include "CAM_Module.h"
 
+/*!Constructor.*/
 CAM_Study::CAM_Study( SUIT_Application* app )
 : SUIT_Study( app )
 {
 }
 
+/*!Destructor*/
 CAM_Study::~CAM_Study()
 {
 }
 
+/*!Closing all data models and close document permanently(if \a permanently = true.)
+ * \param permanently - flag
+ */
 void CAM_Study::closeDocument(bool permanently)
 {
   for ( ModelListIterator it( myDataModels ); it.current(); ++it )
@@ -22,17 +27,29 @@ void CAM_Study::closeDocument(bool permanently)
   SUIT_Study::closeDocument(permanently);
 }
 
+/*!Append data model to list.
+ * \param dm - data model for adding
+ */
 bool CAM_Study::appendDataModel( const CAM_DataModel* dm )
 {
   return insertDataModel( dm, myDataModels.count() );
 }
 
+/*!Insert data model \a dm after \a other
+ * \param dm - data model for adding
+ * \param other - previus data model for \a dm
+ */
 bool CAM_Study::insertDataModel( const CAM_DataModel* dm, const CAM_DataModel* other )
 {
   int idx = myDataModels.findRef( other );
   return insertDataModel( dm, idx < 0 ? idx : idx + 1 );
 }
 
+/*!Insert data model with index \a idx. \n
+ * \param dm - data model
+ * \param idx - index for inserting(must be no less zero)
+ * \retval true - if model added successful, else false.
+ */
 bool CAM_Study::insertDataModel( const CAM_DataModel* dm, const int idx )
 {
   if ( !dm || myDataModels.findRef( dm ) != -1 )
@@ -48,6 +65,10 @@ bool CAM_Study::insertDataModel( const CAM_DataModel* dm, const int idx )
   return true;
 }
 
+/*! Remove data model from list
+ * \param dm data model
+ * \retval true - if all ok, else false.
+ */
 bool CAM_Study::removeDataModel( const CAM_DataModel* dm )
 {
   if ( !dm )
@@ -60,11 +81,18 @@ bool CAM_Study::removeDataModel( const CAM_DataModel* dm )
   return myDataModels.remove( dm );
 }
 
+/*!Check data model contains in list.
+ * \param dm - data model
+ * \retval true - if data model in list, else false.
+ */
 bool CAM_Study::containsDataModel( const CAM_DataModel* dm ) const
 {
   return myDataModels.contains( dm );
 }
 
+/*!Gets list of all data models.
+ * \param lst - output data model list.
+ */
 void CAM_Study::dataModels( ModelList& lst ) const
 {
   lst.clear();
@@ -72,6 +100,7 @@ void CAM_Study::dataModels( ModelList& lst ) const
     lst.append( it.current() );
 }
 
+/*! Open data model \a dModel, if it saved*/
 void CAM_Study::dataModelInserted( const CAM_DataModel* dModel )
 {
   CAM_DataModel* dm = (CAM_DataModel*)dModel;
@@ -86,16 +115,19 @@ void CAM_Study::dataModelInserted( const CAM_DataModel* dModel )
   }
 }
 
+/*! \retval false*/
 bool CAM_Study::openDataModel( const QString&, CAM_DataModel* )
 {
   return false;
 }
 
+/*! \retval false*/
 bool CAM_Study::saveDataModel( const QString&, CAM_DataModel* )
 {
   return false;
 }
 
+/*! Public slot. Update model root.*/
 void CAM_Study::updateModelRoot( const CAM_DataModel* dm )
 {
   if ( !root() )
diff --git a/src/CAM/CAM_Study.h b/src/CAM/CAM_Study.h
index 57e07a031..071b8f1bd 100755
--- a/src/CAM/CAM_Study.h
+++ b/src/CAM/CAM_Study.h
@@ -27,9 +27,12 @@ public:
 
   virtual void closeDocument(bool permanently = true);
 
+  /** @name Insert data model methods.*/
+  //@{
   bool         appendDataModel( const CAM_DataModel* );
   virtual bool insertDataModel( const CAM_DataModel*, const int = -1 );
   bool         insertDataModel( const CAM_DataModel*, const CAM_DataModel* );
+  //@}
 
   virtual bool removeDataModel( const CAM_DataModel* );
 
@@ -46,6 +49,7 @@ protected slots:
   virtual void updateModelRoot( const CAM_DataModel* );
 
 private:
+  //! Data model list
   ModelList    myDataModels;
 };
 
-- 
2.39.2