From 09d02e9a98ff61c9f4ff2ecaa2f7ac42d577ae4f Mon Sep 17 00:00:00 2001
From: vsr <vsr@opencascade.com>
Date: Thu, 29 Mar 2012 15:39:44 +0000
Subject: [PATCH] Improve dev docs

---
 src/GenericObj/SALOME_GenericObj_i.cc | 119 ++++++++++++++++++--------
 src/GenericObj/SALOME_GenericObj_i.hh |  20 ++---
 2 files changed, 92 insertions(+), 47 deletions(-)

diff --git a/src/GenericObj/SALOME_GenericObj_i.cc b/src/GenericObj/SALOME_GenericObj_i.cc
index a349dec17..97515c4ce 100644
--- a/src/GenericObj/SALOME_GenericObj_i.cc
+++ b/src/GenericObj/SALOME_GenericObj_i.cc
@@ -20,11 +20,9 @@
 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
 //
 
-//  SALOME_GenericObj_i_CC
 //  File   : SALOME_GenericObj_i.cc
-//  Author : Alexey PETROV
-//  Module : SALOME
-//
+//  Author : Alexey PETROV, Open CASCADE S.A.S. (alexey.petrov@opencascade.com)
+
 #include "SALOME_GenericObj_i.hh"
 #include "utilities.h"
 
@@ -34,46 +32,97 @@ static int MYDEBUG = 0;
 static int MYDEBUG = 0;
 #endif
 
-using namespace SALOME;
+namespace SALOME
+{
+
+  /*!
+    \class SALOME::GenericObj_i
+    \brief Implementation of the base servant for SALOME objects with reference counter.
+
+    This class can be used to implement data entities with life-cycle management based on
+    the reference counting. 
+
+    The object is initially created with the reference counter equal to 1.
+    The function Register() can be used to incrfement the reference counter.
+    Function UnRegister() should be used to decrement reference counter.
+    As soon as reference counter goes to zero, the object is automatically deactivated in POA
+    (and, eventually its destructor is automatically called).
+  */
+  
+  /*!
+    \brief Constructor.
+    Creates an object with the reference counter initially set to 1.
+  
+    The default POA for the servant can be passed as a parameter \a thePOA.
+    By default, root POA is used.
 
-GenericObj_i::GenericObj_i(PortableServer::POA_ptr thePOA): myRefCounter(1){
-  if(MYDEBUG) 
-    MESSAGE("GenericObj_i::GenericObj_i() - this = "<<this<<
-	    "; CORBA::is_nil(thePOA) = "<<CORBA::is_nil(thePOA));
-  if(CORBA::is_nil(thePOA))
+    \param thePOA optional default POA for the servant
+  */
+  GenericObj_i::GenericObj_i(PortableServer::POA_ptr thePOA): myRefCounter(1)
+  {
+    if(MYDEBUG) 
+      MESSAGE("GenericObj_i::GenericObj_i() - this = "<<this<<
+	      "; CORBA::is_nil(thePOA) = "<<CORBA::is_nil(thePOA));
+    if(CORBA::is_nil(thePOA)) {
 #ifndef WIN32
-    myPOA = PortableServer::ServantBase::_default_POA();
+      myPOA = PortableServer::ServantBase::_default_POA();
 #else
-    myPOA = ServantBase::_default_POA();
+      myPOA = ServantBase::_default_POA();
 #endif
-  else
-    myPOA = PortableServer::POA::_duplicate(thePOA);
-}
+    }
+    else {
+      myPOA = PortableServer::POA::_duplicate(thePOA);
+    }
+  }
 
+  /*!
+    \brief Get default POA for the servant object.
 
-PortableServer::POA_ptr GenericObj_i::_default_POA(){
-  return PortableServer::POA::_duplicate(myPOA);
-}
+    This function is implicitly called from "_this()" function.
+    Default POA can be set via the constructor.
 
+    \return reference to the default POA for the servant
+  */
+  PortableServer::POA_ptr GenericObj_i::_default_POA()
+  {
+    return PortableServer::POA::_duplicate(myPOA);
+  }
 
-void GenericObj_i::Register(){
-  if(MYDEBUG)
-    MESSAGE("GenericObj_i::Register "<<this<<"; myRefCounter = "<<myRefCounter)
-  ++myRefCounter;
-}
+  /*!
+    \brief Increment reference counter.
+  */
+  void GenericObj_i::Register()
+  {
+    if(MYDEBUG)
+      MESSAGE("GenericObj_i::Register "<<this<<"; myRefCounter = "<<myRefCounter);
+    ++myRefCounter;
+  }
 
+  /*!
+    \brief Decrement reference counter.
+
+    As soon as reference counter goes to zero, the object is automatically
+    deactivated.
+  */
+  void GenericObj_i::UnRegister()
+  {
+    if(MYDEBUG)
+      MESSAGE("GenericObj_i::UnRegister "<<this<<"; myRefCounter = "<<myRefCounter);
+    if(--myRefCounter <= 0){
+      PortableServer::ObjectId_var anObjectId = myPOA->servant_to_id(this);
+      myPOA->deactivate_object(anObjectId.in());
+      _remove_ref();
+    }
+  }
 
-void GenericObj_i::UnRegister(){
-  if(MYDEBUG)
-    MESSAGE("GenericObj_i::UnRegister "<<this<<"; myRefCounter = "<<myRefCounter)
-  if(--myRefCounter <= 0){
-    PortableServer::ObjectId_var anObjectId = myPOA->servant_to_id(this);
-    myPOA->deactivate_object(anObjectId.in());
-    _remove_ref();
+  /*!
+    \brief Decrement reference counter.
+    \deprecated Use UnRegister() instead.
+  */
+  void GenericObj_i::Destroy()
+  {
+    MESSAGE("WARNING SALOME::GenericObj::Destroy() function is obsolete! Use UnRegister() instead.");
+    UnRegister();
   }
-}
 
-void GenericObj_i::Destroy(){
-  MESSAGE("WARNING SALOME::GenericObj::Destroy() function is obsolete! Use UnRegister() instead.");
-  UnRegister();
-}
+}; // end of namespace SALOME
diff --git a/src/GenericObj/SALOME_GenericObj_i.hh b/src/GenericObj/SALOME_GenericObj_i.hh
index 35fc1f361..4a406115d 100644
--- a/src/GenericObj/SALOME_GenericObj_i.hh
+++ b/src/GenericObj/SALOME_GenericObj_i.hh
@@ -20,11 +20,9 @@
 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
 //
 
-//  SALOME_GenericObj_i_HH
 //  File   : SALOME_GenericObj_i.hh
-//  Author : Alexey PETROV
-//  Module : SALOME
-//
+//  Author : Alexey PETROV, Open CASCADE S.A.S. (alexey.petrov@opencascade.com)
+
 #ifndef SALOME_GenericObj_i_HH
 #define SALOME_GenericObj_i_HH
 
@@ -47,7 +45,8 @@
 #pragma warning(disable:4251) // Warning DLL Interface ...
 #endif
 
-namespace SALOME{
+namespace SALOME
+{
   class GENERICOBJ_EXPORT GenericObj_i : 
     public virtual POA_SALOME::GenericObj,
     public virtual PortableServer::ServantBase
@@ -55,20 +54,17 @@ namespace SALOME{
   protected:
     PortableServer::POA_var myPOA;
     int myRefCounter;
+
   public:
-    // In the constructor you can provide default POA for the servant
     GenericObj_i(PortableServer::POA_ptr thePOA = PortableServer::POA::_nil());
-    // The function is used implicetly in "_this" function
+
     virtual PortableServer::POA_ptr _default_POA();
-  public: // Follow functions is IDL defined
-    /*! Increase the reference count (mark as used by another object).*/
+
+  public:
     virtual void Register();
-    /*! Decrease the reference count (release by another object).*/
     virtual void UnRegister();
-    /*! \brief Obsolete, left for compatibility reasons only. Use UnRegister() instead.*/
     virtual void Destroy();
   };
 }
 
 #endif
-
-- 
2.39.2