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

1 files changed, 171 insertions, 162 deletions

diff --git a/TAO/tao/Any.h b/TAO/tao/Any.h
index 40a48e12427..90aa4997cac 100644
--- a/TAO/tao/Any.h
+++ b/TAO/tao/Any.h
@@ -1,19 +1,16 @@
 // This may look like C, but it's really -*- C++ -*-
-// $Id$
-
-// ============================================================================
-//
-// = LIBRARY
-//    TAO
-//
-// = FILENAME
-//    Any.h
-//
-// = AUTHOR
-//     Copyright 1994-1995 by Sun Microsystems, Inc.
-//     and Aniruddha Gokhale.
-//
-// ============================================================================
+
+//=============================================================================
+/**
+ *  @file    Any.h
+ *
+ *  $Id$
+ *
+ *  @author  Copyright 1994-1995 by Sun Microsystems
+ *  @author Inc.  and Aniruddha Gokhale.
+ */
+//=============================================================================
+
 
 #ifndef TAO_ANY_H
 #define TAO_ANY_H
@@ -29,37 +26,36 @@
 #include "tao/Object.h"
 #include "tao/Typecode.h"
 
+/**
+ * @class CORBA_Any
+ *
+ * @brief Class "Any" can wrap values of any type, with the assistance
+ * of a TypeCode to describe that type.
+ *
+ * This includes three constructors, a destructor, and a "replace"
+ * method for the "Any" data type.  "Any" values pair a pointer to
+ * a data structure in the native binary representation (e.g. C
+ * struct) with a TypeCode that describes that data structure.
+ * The copy constructor and the destructor each use the TypeCode
+ * interpreter with specialized "visit" callback routines.  The
+ * "visit" routines are used respectively to make "deep copies"
+ * and perform "deep frees" of the aritrary values as described by
+ * the "Any" value's typecode.
+ * Note that these "visit" routines are called directly, and they
+ * choose whether or not to use the TypeCode interpreter to
+ * examine constituents.  In the simple cases, the "visit"
+ * routines can do their work without any further calls; only for
+ * constructed types is the interpreter's knowledge really
+ * required.
+ * THREADING NOTE: "Any" is a data structure which must be
+ * protected by external critical sections.  Like simpler numeric
+ * types, "Any" instances are accessed and modified atomically.
+ * This implementation is reentrant, so that independent "Any"
+ * values may be manipulated concurrently when the underlying
+ * programming environment is itself reentrant.
+ */
 class TAO_Export CORBA_Any
 {
-  // = TITLE
-  //   Class "Any" can wrap values of any type, with the assistance
-  //   of a TypeCode to describe that type.
-  //
-  // = DESCRIPTION
-  //   This includes three constructors, a destructor, and a "replace"
-  //   method for the "Any" data type.  "Any" values pair a pointer to
-  //   a data structure in the native binary representation (e.g. C
-  //   struct) with a TypeCode that describes that data structure.
-  //
-  //   The copy constructor and the destructor each use the TypeCode
-  //   interpreter with specialized "visit" callback routines.  The
-  //   "visit" routines are used respectively to make "deep copies"
-  //   and perform "deep frees" of the aritrary values as described by
-  //   the "Any" value's typecode.
-  //
-  //   Note that these "visit" routines are called directly, and they
-  //   choose whether or not to use the TypeCode interpreter to
-  //   examine constituents.  In the simple cases, the "visit"
-  //   routines can do their work without any further calls; only for
-  //   constructed types is the interpreter's knowledge really
-  //   required.
-  //
-  //   THREADING NOTE: "Any" is a data structure which must be
-  //   protected by external critical sections.  Like simpler numeric
-  //   types, "Any" instances are accessed and modified atomically.
-  //   This implementation is reentrant, so that independent "Any"
-  //   values may be manipulated concurrently when the underlying
-  //   programming environment is itself reentrant.
 public:
 
   // = Minor codes for exceptional returns
@@ -72,128 +68,130 @@ public:
 
   // = Initialization and termination operations.
 
+  /// Default constructor.
   CORBA_Any (void);
-  // Default constructor.
 
+  /// Constructor.
   CORBA_Any (CORBA::TypeCode_ptr type,
              CORBA::Environment &ACE_TRY_ENV
                  = TAO_default_environment ());
-  // Constructor.
 
   // = TAO extension
+  /**
+   * Constructor. Used by DynAny and others to optimize Any activities
+   * by using CDR. The dummy arg is to keep calls like CORBA_Any foo
+   * (CORBA::TypeCode_ptr bar (NULL), NULL) from being confused with
+   * the constructor above.
+   */
   CORBA_Any (CORBA::TypeCode_ptr type,
              CORBA::UShort dummy,
              int byte_order,
              const ACE_Message_Block* mb);
-  // Constructor. Used by DynAny and others to optimize Any activities
-  // by using CDR. The dummy arg is to keep calls like CORBA_Any foo
-  // (CORBA::TypeCode_ptr bar (NULL), NULL) from being confused with
-  // the constructor above.
 
+  /// Copy constructor.
   CORBA_Any (const CORBA_Any &a);
-  // Copy constructor.
 
+  /// Destructor.
   ~CORBA_Any (void);
-  // Destructor.
 
+  /// assignment operator
   CORBA_Any &operator= (const CORBA_Any &);
-  // assignment operator
 
   // = NOTE: 94-9-14 has assignment operator plus many insertion, as
   // specified below.
 
   // =type safe insertion
 
+  /// Insert a short.
   void operator<<= (CORBA::Short);
-  // Insert a short.
 
+  /// Insert an unsigned short.
   void operator<<= (CORBA::UShort);
-  // Insert an unsigned short.
 
+  /// Insert a long.
   void operator<<= (CORBA::Long);
-  // Insert a long.
 
+  /// Insert an unsigned long.
   void operator<<= (CORBA::ULong);
-  // Insert an unsigned long.
 
+  /// Insert a long long.
   void operator<<= (CORBA::LongLong);
-  // Insert a long long.
 
+  /// Insert an unsigned long long.
   void operator<<= (CORBA::ULongLong);
-  // Insert an unsigned long long.
 
+  /// Insert a float.
   void operator<<= (CORBA::Float);
-  // Insert a float.
 
+  /// Insert a double.
   void operator<<= (CORBA::Double);
-  // Insert a double.
 
+  /// Insert a long double.
   void operator<<= (CORBA::LongDouble);
-  // Insert a long double.
 
+  /// Insert an Any, copying.
   void operator<<= (const CORBA_Any&);
-  // Insert an Any, copying.
 
+  /// Insert an Any, non-copying.
   void operator<<= (CORBA_Any_ptr);
-  // Insert an Any, non-copying.
 
+  /// Insert unbounded string
   void operator<<= (const char*);
-  // Insert unbounded string
 
+  /// Insert unbounded wide string.
   void operator<<= (const CORBA::WChar*);
-  // Insert unbounded wide string.
 
+  /// Insert a TypeCode.
   void operator<<= (CORBA::TypeCode_ptr);
-  // Insert a TypeCode.
 
+  /// Insert an object reference, copying.
   void operator<<= (const CORBA::Object_ptr);
-  // Insert an object reference, copying.
 
+  /// Insert an object reference, non-copying. Any assumes the ownership
+  /// of the object.
   void operator<<= (CORBA::Object_ptr *);
-  // Insert an object reference, non-copying. Any assumes the ownership
-  // of the object.
 
   // =Type safe extraction.
 
+  /// Extract a short.
   CORBA::Boolean operator>>= (CORBA::Short&) const;
-  // Extract a short.
 
+  /// Extract an unsigned short.
   CORBA::Boolean operator>>= (CORBA::UShort&) const;
-  // Extract an unsigned short.
 
+  /// Extract a long.
   CORBA::Boolean operator>>= (CORBA::Long&) const;
-  // Extract a long.
 
+  /// Extract an unsigned long.
   CORBA::Boolean operator>>= (CORBA::ULong&) const;
-  // Extract an unsigned long.
 
+  /// Extract a long long.
   CORBA::Boolean operator>>= (CORBA::LongLong&) const;
-  // Extract a long long.
 
+  /// Extract an unsigned long long.
   CORBA::Boolean operator>>= (CORBA::ULongLong&) const;
-  // Extract an unsigned long long.
 
+  /// Extract a float.
   CORBA::Boolean operator>>= (CORBA::Float&) const;
-  // Extract a float.
 
+  /// Extract a double.
   CORBA::Boolean operator>>= (CORBA::Double&) const;
-  // Extract a double.
 
+  /// Extract a long double.
   CORBA::Boolean operator>>= (CORBA::LongDouble&) const;
-  // Extract a long double.
 
+  /// Extract an Any.
   CORBA::Boolean operator>>= (CORBA_Any&) const; // non-spec
   CORBA::Boolean operator>>= (const CORBA_Any*&) const;
-  // Extract an Any.
 
+  /// Extract a TypeCode.
   CORBA::Boolean operator>>= (CORBA::TypeCode_ptr&) const;
-  // Extract a TypeCode.
 
+  /// Extract an unbounded string
   CORBA::Boolean operator>>= (const char*&) const;
-  // Extract an unbounded string
 
+  /// Extract an unbounded wide string.
   CORBA::Boolean operator>>= (const CORBA::WChar*&) const;
-  // Extract an unbounded wide string.
 
   // = Special types.
 
@@ -209,29 +207,29 @@ public:
   typedef ACE_OutputCDR::from_string from_string;
   typedef ACE_OutputCDR::from_wstring from_wstring;
 
+  /// Insert a boolean.
   void operator<<= (from_boolean);
-  // Insert a boolean.
 
+  /// Insert a char.
   void operator<<= (from_char);
-  // Insert a char.
 
+  /// Insert a wchar.
   void operator<<= (from_wchar);
-  // Insert a wchar.
 
+  /// Insert an octet.
   void operator<<= (from_octet);
-  // Insert an octet.
 
+  /// Insert a bounded string.
   void operator<<= (from_string);
-  // Insert a bounded string.
 
+  /// Insert a bounded wide string.
   void operator<<= (from_wstring);
-  // Insert a bounded wide string.
 
+  /// Insert an exception into the Any (copying)
   void operator<<= (const CORBA_Exception &exception);
-  // Insert an exception into the Any (copying)
 
+  /// Insert an exception into the Any (non-copying).
   void operator<<= (CORBA_Exception *exception);
-  // Insert an exception into the Any (non-copying).
 
   // = Special types.
 
@@ -256,90 +254,94 @@ public:
 
   // extraction of the special types
 
+  /// extract a boolean
   CORBA::Boolean operator>>= (to_boolean) const;
-  // extract a boolean
 
+  /// extract an octet
   CORBA::Boolean operator>>= (to_octet) const;
-  // extract an octet
 
+  /// extract a char
   CORBA::Boolean operator>>= (to_char) const;
-  // extract a char
 
+  /// extract a wchar
   CORBA::Boolean operator>>= (to_wchar) const;
-  // extract a wchar
 
+  /// extract a bounded string
   CORBA::Boolean operator>>= (to_string) const;
-  // extract a bounded string
 
+  /// extract a bounded wide string
   CORBA::Boolean operator>>= (to_wstring) const;
-  // extract a bounded wide string
 
+  /// extract an object reference
   CORBA::Boolean operator>>= (to_object) const;
-  // extract an object reference
 
   // the following are unsafe operations
   // ORBOS/90-01-11, pg 672: For C++ mapping using the CORBA_Environment
   // parameter, two forms of the replace method are provided.
 
+  /// Return TypeCode of the element stored in the Any.
   CORBA::TypeCode_ptr type (void) const;
-  // Return TypeCode of the element stored in the Any.
 
+  /// For use along with <<= of a value of aliased type when the alias must
+  /// be preserved.
   void type (CORBA::TypeCode_ptr type,
              CORBA_Environment &ACE_TRY_ENV =
                TAO_default_environment ());
-  // For use along with <<= of a value of aliased type when the alias must
-  // be preserved.
 
+  /**
+   * Returns 0 if the Any has not been assigned a value, following the
+   * CORBA spec (ORBOS/98-01-11) it returns a non-zero value
+   * otherwise. TAO does *not* guarantee that this value may be casted
+   * to the contained type safely.
+   */
   const void *value (void) const;
-  // Returns 0 if the Any has not been assigned a value, following the
-  // CORBA spec (ORBOS/98-01-11) it returns a non-zero value
-  // otherwise. TAO does *not* guarantee that this value may be casted
-  // to the contained type safely.
 
   // = TAO extensions
+  /**
+   * Reports whether the Any own the data or not. This is used by the
+   * >>= operators generated by the IDL compiler. The >>= operator
+   * checks if the Any owns the data. If it does, then it will simply
+   * retrieve the data from internal cache.  Otherwise, the operator
+   * will have to decode the cdr string.
+   */
   CORBA::Boolean any_owns_data (void) const;
-  // Reports whether the Any own the data or not. This is used by the
-  // >>= operators generated by the IDL compiler. The >>= operator
-  // checks if the Any owns the data. If it does, then it will simply
-  // retrieve the data from internal cache.  Otherwise, the operator
-  // will have to decode the cdr string.
 
+  /// Message block accessor.
+  /// Get the byte order inside the CDR stream.
   ACE_Message_Block* _tao_get_cdr (void) const;
-  // Message block accessor.
   int _tao_byte_order (void) const;
-  // Get the byte order inside the CDR stream.
 
+  /// Generated data types define a 'destructor' function that
+  /// correctly destroys an object stored in the Any.
   typedef void (*_tao_destructor)(void*);
-  // Generated data types define a 'destructor' function that
-  // correctly destroys an object stored in the Any.
 
+  /// Replace via message block instead of <value_>.
   void _tao_replace (CORBA::TypeCode_ptr,
                      int byte_order,
                      const ACE_Message_Block *mb);
-  // Replace via message block instead of <value_>.
 
+  /// Replace all the contents of the any, used in the <<= operators.
   void _tao_replace (CORBA::TypeCode_ptr type,
                      int byte_order,
                      const ACE_Message_Block *mb,
                      CORBA::Boolean any_owns_data,
                      void* value,
                      CORBA::Any::_tao_destructor destructor);
-  // Replace all the contents of the any, used in the <<= operators.
 
+  /// Replace the value of the Any, used in the >>= operators.
   void _tao_replace (CORBA::TypeCode_ptr type,
                      CORBA::Boolean any_owns_data,
                      void* value,
                      CORBA::Any::_tao_destructor destructor);
-  // Replace the value of the Any, used in the >>= operators.
 
+  /// Encode the contents of the Any into <cdr>
   void _tao_encode (TAO_OutputCDR &cdr,
                     TAO_ORB_Core *orb_core,
                     CORBA::Environment &ACE_TRY_ENV);
-  // Encode the contents of the Any into <cdr>
 
+  /// Decode the <cdr> using the typecode in the Any object.
   void _tao_decode (TAO_InputCDR &cdr,
                     CORBA::Environment &ACE_TRY_ENV);
-  // Decode the <cdr> using the typecode in the Any object.
 
 #if !defined(__GNUC__) || __GNUC__ > 2 || __GNUC_MINOR__ >= 8
   typedef CORBA_Any_ptr _ptr_type;
@@ -347,32 +349,32 @@ public:
 #endif /* __GNUC__ */
   // Useful for template programming.
 
+  /// Used to release Anys contained into anys.
   static void _tao_any_destructor (void*);
   static void _tao_any_string_destructor (void*);
   static void _tao_any_wstring_destructor (void*);
   static void _tao_any_tc_destructor (void*);
-  // Used to release Anys contained into anys.
 
 protected:
+  /// Release the <value_>.
   void free_value (void);
-  // Release the <value_>.
 
 private:
+  /// Typecode for the <Any>.
   CORBA::TypeCode_var type_;
-  // Typecode for the <Any>.
 
+  /// encoded value.
   int byte_order_;
   ACE_Message_Block *cdr_;
-  // encoded value.
 
+  /// Flag that indicates the ORB is responsible for deleting the data.
   CORBA::Boolean any_owns_data_;
-  // Flag that indicates the ORB is responsible for deleting the data.
 
+  /// Value for the <Any>.
   void *value_;
-  // Value for the <Any>.
 
+  /// If not zero this is the function used to destroy objects.
   CORBA::Any::_tao_destructor destructor_;
-  // If not zero this is the function used to destroy objects.
 
   // 94-9-14 hides unsigned char insert/extract
   void operator<<= (unsigned char);
@@ -382,102 +384,109 @@ private:
   friend class TAO_Marshal_Any;
 };
 
+/**
+ * @class CORBA_Any_var
+ *
+ * @brief Provide for automatic storage deallocation on going out of
+ * scope.
+ */
 class TAO_Export CORBA_Any_var
 {
-  // = TITLE
-  //   Provide for automatic storage deallocation on going out of
-  //   scope.
 public:
+  /// default constructor
   CORBA_Any_var (void);
-  // default constructor
 
+  /// construct from an Any pointer
   CORBA_Any_var (CORBA_Any *a);
-  // construct from an Any pointer
 
+  /// copy constructor
   CORBA_Any_var (const CORBA_Any_var &a);
-  // copy constructor
 
+  /// destructor
   ~CORBA_Any_var (void);
-  // destructor
 
+  /// assignment from a pointer to Any
   CORBA_Any_var &operator= (CORBA_Any *a);
-  // assignment from a pointer to Any
 
+  /**
+   * assignment from an Any_var
+   * This operation requires memory allocation.
+   * If the allocation fails, *this is returned
+   * unmodified.
+   */
   CORBA_Any_var &operator= (const CORBA_Any_var &a);
-  // assignment from an Any_var
-  // This operation requires memory allocation.
-  // If the allocation fails, *this is returned
-  // unmodified.
 
+  /// arrow operator (smart pointer)
   CORBA_Any *operator-> (void);
-  // arrow operator (smart pointer)
 
+  /// cast
   operator const CORBA_Any *() const;
-  // cast
 
+  /// cast
   operator CORBA_Any *&();
-  // cast
 
+  /// for in Any parameter
   const CORBA_Any &in (void) const;
-  // for in Any parameter
 
+  /// for inout Any parameter
   CORBA_Any &inout (void);
-  // for inout Any parameter
 
+  /// for out Any parameter
   CORBA_Any *&out (void);
-  // for out Any parameter
 
+  /// for Any return types
   CORBA_Any *_retn (void);
-  // for Any return types
 
 private:
+  /// Holds the Any.
   CORBA_Any *ptr_;
-  // Holds the Any.
 };
 
+/**
+ * @class CORBA_Any_out
+ *
+ * @brief CORBA_Any_out
+ *
+ * The _out class for CORBA_Any. This is used to help in
+ * managing the out parameters.
+ */
 class TAO_Export CORBA_Any_out
 {
-  // = TITLE
-  //   CORBA_Any_out
-  //
-  // = DESCRIPTION
-  //   The _out class for CORBA_Any. This is used to help in
-  //   managing the out parameters.
 public:
   // = operations.
 
+  /// construction from a reference to a CORBA_Any
   CORBA_Any_out (CORBA_Any *&p);
-  // construction from a reference to a CORBA_Any
 
+  /// construction from a var
   CORBA_Any_out (CORBA_Any_var &p);
-  // construction from a var
 
+  /// copy constructor
   CORBA_Any_out (const CORBA_Any_out &s);
-  // copy constructor
 
+  /// assignment from a CORBA_Any_out
   CORBA_Any_out &operator= (const CORBA_Any_out &s);
-  // assignment from a CORBA_Any_out
 
+  /// assignment from a CORBA_Any
   CORBA_Any_out &operator= (CORBA_Any *p);
-  // assignment from a CORBA_Any
 
+  /// assignment from a const CORBA_Any
   CORBA_Any_out &operator= (const CORBA_Any *p);
-  // assignment from a const CORBA_Any
 
+  /// cast
   operator CORBA_Any *&();
-  // cast
 
+  /// return underlying instance
   CORBA_Any *& ptr (void);
-  // return underlying instance
 
   CORBA_Any *operator-> (void);
 
 private:
+  /// Instance
   CORBA_Any *&ptr_;
-  // Instance
 
+  /// assignment from _var disallowed
   void operator= (const CORBA_Any_var &);
-  // assignment from _var disallowed
 };
 
 // These operators are too complex to be inline....