ChangeLogTag:Fri Dec 15 11:36:08 2000 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 81 insertions, 74 deletions

diff --git a/TAO/tao/Object.h b/TAO/tao/Object.h
index eec1a76bd2b..aabd9267832 100644
--- a/TAO/tao/Object.h
+++ b/TAO/tao/Object.h
@@ -1,26 +1,23 @@
 // This may look like C, but it's really -*- C++ -*-
-// $Id$
-
-// ============================================================================
-//
-// = LIBRARY
-//    TAO
-//
-// = FILENAME
-//    object.h
-//
-// = DESCRIPTION
-//     Header file for Win32 interface to CORBA's base "Object" type.
-//
-//     A "Object" is an entity that can be the target of an invocation
-//     using an ORB.  All CORBA objects provide this functionality.
-//     See the CORBA 2.0 specification for details.
-//
-// = AUTHOR
-//     Portions Copyright 1994-1995 by Sun Microsystems Inc.
-//     Portions Copyright 1997 by Washington University
-//
-// ============================================================================
+
+//=============================================================================
+/**
+ *  @file    Object.h
+ *
+ *  $Id$
+ *
+ *   Header file for Win32 interface to CORBA's base "Object" type.
+ *
+ *   A "Object" is an entity that can be the target of an invocation
+ *   using an ORB.  All CORBA objects provide this functionality.
+ *   See the CORBA 2.0 specification for details.
+ *
+ *
+ *  @author  Portions Copyright 1994-1995 by Sun Microsystems Inc.
+ *  @author  Portions Copyright 1997 by Washington University
+ */
+//=============================================================================
+
 
 #ifndef TAO_CORBA_OBJECT_H
 #define TAO_CORBA_OBJECT_H
@@ -43,15 +40,16 @@ class TAO_Stub;
 class TAO_Export CORBA_Object
 {
 public:
+  /// destructor
   virtual ~CORBA_Object (void);
-  // destructor
 
+  /// increment the ref count
   static CORBA_Object_ptr _duplicate (CORBA_Object_ptr obj);
-  // increment the ref count
 
+  /// return a NUL object
   static CORBA_Object_ptr _nil (void);
-  // return a NUL object
 
+  /// no-op it is just here to simplify some templates.
   ACE_INLINE_FOR_GNUC
   static CORBA_Object_ptr _narrow (CORBA_Object_ptr obj,
                                    CORBA_Environment &ACE_TRY_ENV =
@@ -59,10 +57,9 @@ public:
   static CORBA_Object_ptr _unchecked_narrow (CORBA_Object_ptr obj,
                                              CORBA_Environment &ACE_TRY_ENV =
                                                  TAO_default_environment ());
-  // no-op it is just here to simplify some templates.
 
+  /// Used in the implementation of CORBA::Any
   static void _tao_any_destructor (void*);
-  // Used in the implementation of CORBA::Any
 
   // These calls correspond to over-the-wire operations, or at least
   // do so in many common cases.  The normal implementation assumes a
@@ -70,20 +67,20 @@ public:
   // making such calls, but may be overridden when it appears
   // appropriate.
 
+  /// determine if we are of the type specified by the "logical_type_id"
   virtual CORBA::Boolean _is_a (const char *logical_type_id,
                                 CORBA_Environment &ACE_TRY_ENV =
                                   TAO_default_environment ());
-  // determine if we are of the type specified by the "logical_type_id"
 
+  /// The repository ID for the most derived class, this is an
+  /// implementation method and does no remote invocations!
   virtual const char* _interface_repository_id (void) const;
-  // The repository ID for the most derived class, this is an
-  // implementation method and does no remote invocations!
 
+  /// Is this object collocated with the servant?
   virtual CORBA::Boolean _is_collocated (void) const;
-  // Is this object collocated with the servant?
 
+  /// Is this a local object?
   virtual CORBA::Boolean _is_local (void) const;
-  // Is this a local object?
 
   virtual TAO_Abstract_ServantBase*_servant (void) const;
 
@@ -92,11 +89,11 @@ public:
   virtual CORBA::Boolean _non_existent (CORBA_Environment &ACE_TRY_ENV =
                                           TAO_default_environment ());
 
+  /// This method is deprecated in the CORBA 2.2 spec, we just return 0
+  /// every time.
   virtual CORBA::ImplementationDef_ptr
       _get_implementation (CORBA_Environment &ACE_TRY_ENV =
                              TAO_default_environment ());
-  // This method is deprecated in the CORBA 2.2 spec, we just return 0
-  // every time.
 
 #if (TAO_HAS_INTERFACE_REPOSITORY == 1)
 
@@ -139,10 +136,10 @@ public:
   // multi-protocol remote invocation interface as is assumed by the
   // calls above ... that's how it can have a default implementation.
 
+  /// DII operation to create a request.
   virtual CORBA::Request_ptr _request (const char *operation,
                                        CORBA_Environment &ACE_TRY_ENV =
                                         TAO_default_environment ());
-  // DII operation to create a request.
 
 #if (TAO_HAS_CORBA_MESSAGING == 1)
 
@@ -175,37 +172,43 @@ public:
 
 #endif /* TAO_HAS_CORBA_MESSAGING == 1 */
 
+  /**
+   * Return a (potentially non-unique) hash value for this object.
+   * This method relies on the representation of the object
+   * reference's private state.  Since that changes easily (when
+   * different ORB protocols are in use) there is no default
+   * implementation.
+   */
   virtual CORBA::ULong _hash (CORBA::ULong maximum,
                               CORBA_Environment &ACE_TRY_ENV =
                                 TAO_default_environment ());
-  // Return a (potentially non-unique) hash value for this object.
-  // This method relies on the representation of the object
-  // reference's private state.  Since that changes easily (when
-  // different ORB protocols are in use) there is no default
-  // implementation.
 
+  /**
+   * Try to determine if this object is the same as <other_obj>.  This
+   * method relies on the representation of the object reference's
+   * private state.  Since that changes easily (when different ORB
+   * protocols are in use) there is no default implementation.
+   */
   virtual CORBA::Boolean _is_equivalent (CORBA::Object_ptr other_obj,
                                          CORBA_Environment &ACE_TRY_ENV =
                                              TAO_default_environment ())
     ACE_THROW_SPEC (());
-  // Try to determine if this object is the same as <other_obj>.  This
-  // method relies on the representation of the object reference's
-  // private state.  Since that changes easily (when different ORB
-  // protocols are in use) there is no default implementation.
 
+  /// Return the object key as an out parameter.  Caller should release
+  /// return value when finished with it.
   virtual TAO_ObjectKey *_key (CORBA_Environment &ACE_TRY_ENV =
                                  TAO_default_environment ());
-  // Return the object key as an out parameter.  Caller should release
-  // return value when finished with it.
 
+  /**
+   * Return a reference to the object key of profile in-use.
+   * If there's no in-use profile, then the program will
+   * probably crash.  This method does not create a new copy.
+   */
   virtual const TAO_ObjectKey &_object_key (void);
-  // Return a reference to the object key of profile in-use.
-  // If there's no in-use profile, then the program will
-  // probably crash.  This method does not create a new copy.
 
+  /// Downcasting this object pointer to some other derived class.
+  /// This QueryInterface stuff only work for local object.
   virtual void * _tao_QueryInterface (ptr_arith_t type);
-  // Downcasting this object pointer to some other derived class.
-  // This QueryInterface stuff only work for local object.
 
 #if !defined(__GNUC__) || __GNUC__ > 2 || __GNUC_MINOR__ >= 8
   typedef CORBA_Object_ptr _ptr_type;
@@ -214,11 +217,11 @@ public:
   // Useful for template programming.
 
   // = Reference count managment.
+  /// Increment the reference count.
   virtual void _add_ref (void);
-  // Increment the reference count.
 
+  /// Decrement the reference count.
   virtual void _remove_ref (void);
-  // Decrement the reference count.
 
   // = TAO extensions
 
@@ -227,54 +230,58 @@ public:
                 TAO_Abstract_ServantBase *servant = 0);
 
 
+  /// get the underlying stub object
   virtual TAO_Stub *_stubobj (void) const;
-  // get the underlying stub object
 
+  /// Sets the proxy broker.
   virtual void _proxy_broker (TAO_Object_Proxy_Broker *proxy_broker);
-  // Sets the proxy broker.
 
+  /// Gets the proxy broker.
   virtual TAO_Object_Proxy_Broker *_proxy_broker (void);
-  // Gets the proxy broker.
 
 protected:
+  /// Initializing a local object.
   CORBA_Object (int dummy);
-  // Initializing a local object.
 
   // = Internal Reference count managment.
+  /// Increment the reference count.
   CORBA::ULong _incr_refcnt (void);
-  // Increment the reference count.
 
+  /// Decrement the reference count.
   CORBA::ULong _decr_refcnt (void);
-  // Decrement the reference count.
 
+  /// Flag to indicate collocation.  It is 0 except for collocated
+  /// objects.
   CORBA::Boolean is_collocated_;
-  // Flag to indicate collocation.  It is 0 except for collocated
-  // objects.
 
+  /// Servant pointer.  It is 0 except for collocated objects.
   TAO_Abstract_ServantBase *servant_;
-  // Servant pointer.  It is 0 except for collocated objects.
 
+  /// Specify whether this is a local object or not.
   CORBA::Boolean is_local_;
-  // Specify whether this is a local object or not.
 
+  /**
+   * Pointer to the Proxy Broker i.e. the instance
+   * that takes care of getting the right proxy
+   * for performing a given call.
+   */
   TAO_Object_Proxy_Broker *proxy_broker_;
-  // Pointer to the Proxy Broker i.e. the instance
-  // that takes care of getting the right proxy
-  // for performing a given call.
 
 private:
+  /**
+   * Pointer to the protocol-specific "object" containing important
+   * profiling information regarding this proxy.
+   * The protocol proxy is (potentially) shared among several
+   * CORBA_Objects
+   */
   TAO_Stub *protocol_proxy_;
-  // Pointer to the protocol-specific "object" containing important
-  // profiling information regarding this proxy.
-  // The protocol proxy is (potentially) shared among several
-  // CORBA_Objects
 
+  /// Number of outstanding references to this object.
   CORBA::ULong refcount_;
-  // Number of outstanding references to this object.
 
+  /// Protect the reference count, this is OK because we do no
+  /// duplicates or releases on the critical path.
   ACE_SYNCH_MUTEX refcount_lock_;
-  // Protect the reference count, this is OK because we do no
-  // duplicates or releases on the critical path.
 
   // = Unimplemented methods
   CORBA_Object (const CORBA_Object &);
@@ -293,9 +300,9 @@ public:
   CORBA_Object_var &operator= (const CORBA_Object_var &);
   CORBA::Object_ptr operator-> (void) const;
 
+  /// in, inout, out, _retn
   operator const CORBA::Object_ptr &() const;
   operator CORBA::Object_ptr &();
-  // in, inout, out, _retn
   CORBA::Object_ptr in (void) const;
   CORBA::Object_ptr &inout (void);
   CORBA::Object_ptr &out (void);