zeroc-ice 3.7.0 → 3.7.1

data/ext/ice/cpp/include/Ice/InstanceF.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/include/Ice/InterfaceByValue.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -19,20 +19,36 @@
 namespace Ice
 {
 
+/**
+ * Represents an instance of a Slice interface that was marshaled by value.
+ * \headerfile Ice/Ice.h
+ */
 template<typename T>
 class InterfaceByValue : public ValueHelper<InterfaceByValue<T>, Value>
 {
 public:
+    /**
+     * Obtains the Slice type ID of this exception.
+     * @return The fully-scoped type ID.
+     */
     virtual std::string ice_id() const
     {
         return T::ice_staticId();
     }
 
+    /**
+     * Obtains the Slice type ID of this exception.
+     * @return The fully-scoped type ID.
+     */
     static const std::string& ice_staticId()
     {
         return T::ice_staticId();
     }
 
+    /**
+     * Returns an empty tuple.
+     * @return The empty tuple.
+     */
     std::tuple<> ice_tuple() const
     {
         return std::tie();

data/ext/ice/cpp/include/Ice/LocalObject.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -22,6 +22,10 @@
 namespace Ice
 {
 
+/**
+ * Base class for local Slice classes and interfaces.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API LocalObject : public virtual ::IceUtil::Shared
 {
 public:

data/ext/ice/cpp/include/Ice/LocalObjectF.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/include/Ice/LoggerUtil.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -18,19 +18,27 @@
 namespace Ice
 {
 
+/**
+ * Base class for logger output utility classes.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API LoggerOutputBase : private IceUtil::noncopyable
 {
 public:
 
+    /** Obtains the collected output. */
     std::string str() const;
 
+    /// \cond INTERNAL
     std::ostringstream& _stream(); // For internal use only. Don't use in your code.
+    /// \endcond
 
 private:
 
     std::ostringstream _os;
 };
 
+/// \cond INTERNAL
 ICE_API LoggerOutputBase& loggerInsert(LoggerOutputBase& out, const IceUtil::Exception& ex);
 
 template<typename T>
@@ -92,7 +100,12 @@ operator<<(LoggerOutputBase& out, const ::std::exception& ex)
 }
 
 ICE_API LoggerOutputBase& operator<<(LoggerOutputBase&, std::ios_base& (*)(std::ios_base&));
+/// \endcond
 
+/**
+ * Collects output and flushes it via a logger method.
+ * \headerfile Ice/Ice.h
+ */
 template<class L, class LPtr, void (L::*output)(const std::string&)>
 class LoggerOutput : public LoggerOutputBase
 {
@@ -106,6 +119,7 @@ public:
         flush();
     }
 
+    /** Flushes the colleted output to the logger method. */
     inline void flush()
     {
         std::string s = _stream().str();
@@ -122,10 +136,19 @@ private:
     LPtr _logger;
 };
 
+/** Flushes output to Logger::print. */
 typedef LoggerOutput<Logger, LoggerPtr, &Logger::print> Print;
+
+/** Flushes output to Logger::warning. */
 typedef LoggerOutput<Logger, LoggerPtr, &Logger::warning> Warning;
+
+/** Flushes output to Logger::error. */
 typedef LoggerOutput<Logger, LoggerPtr, &Logger::error> Error;
 
+/**
+ * Flushes output to Logger::trace.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Trace : public LoggerOutputBase
 {
 public:
@@ -139,18 +162,26 @@ private:
     std::string _category;
 };
 
-//
-// A special plug-in that installs a logger during a communicator's initialization.
-// Both initialize and destroy are no-op. See Ice::InitializationData.
-//
+/**
+ * A special plug-in that installs a logger during a communicator's initialization.
+ * Both initialize and destroy are no-op. See Ice::InitializationData.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API LoggerPlugin : public Ice::Plugin
 {
 public:
 
-    LoggerPlugin(const CommunicatorPtr& communicator, const LoggerPtr&);
+    /**
+     * Constructs the plug-in with a target communicator and a logger.
+     * @param communicator The communicator in which to install the logger.
+     * @param logger The logger to be installed.
+     */
+    LoggerPlugin(const CommunicatorPtr& communicator, const LoggerPtr& logger);
 
+    /** This method is a no-op. */
     virtual void initialize();
 
+    /** This method is a no-op. */
     virtual void destroy();
 };
 

data/ext/ice/cpp/include/Ice/MetricsAdminI.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -36,8 +36,10 @@
 namespace IceMX
 {
 
+/// \cond INTERNAL
 class Updater;
 template<typename T> class MetricsHelperT;
+/// \endcond
 
 }
 

data/ext/ice/cpp/include/Ice/MetricsFunctional.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -92,6 +92,7 @@ template<typename R> struct ReferenceWrapper<const R&>
 namespace IceMX
 {
 
+/// \cond INTERNAL
 template<class T, typename Y, typename Func> struct ApplyOnMember
 {
     ApplyOnMember(Y T::*m, Func f) : func(f), member(m)
@@ -156,6 +157,7 @@ template<class T, typename Y> ApplyOnMember<T, Y, Decrement<Y> > dec(Y T::*membe
 {
     return applyOnMember(member, Decrement<Y>());
 }
+/// \endcond
 
 }
 

data/ext/ice/cpp/include/Ice/MetricsObserverI.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -26,6 +26,7 @@
 namespace IceMX
 {
 
+/// \cond INTERNAL
 template<typename T> class MetricsHelperT
 {
 public:
@@ -652,6 +653,7 @@ private:
 };
 
 typedef ObserverT<Metrics> ObserverI;
+/// \endcond
 
 }
 

data/ext/ice/cpp/include/Ice/NativePropertiesAdmin.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -15,36 +15,47 @@
 namespace Ice
 {
 
-//
-// An application can be notified when its configuration properties are modified
-// via the Properties admin facet. The application must define a subclass of
-// PropertiesAdminUpdateCallback and register it with the facet. The facet
-// implements the class NativePropertiesAdmin, so the application needs to
-// downcast the facet to this type in order to register the callback.
-//
-// For example:
-//
-// Ice::ObjectPtr obj = communicator->findAdminFacet("Properties");
-// assert(obj); // May be null if the facet is not enabled
-// NativePropertiesAdminPtr facet = NativePropertiesAdminPtr::dynamicCast(obj);
-// PropertiesAdminUpdateCallbackPtr myCallback = ...;
-// facet->addUpdateCallback(myCallback);
-//
-// Ice ignores any exceptions raised by the callback.
-//
-
 #ifndef ICE_CPP11_MAPPING
+/**
+ * An application can be notified when its configuration properties are modified
+ * via the Properties admin facet. The application must define a subclass of
+ * PropertiesAdminUpdateCallback and register it with the facet. The facet
+ * implements the class NativePropertiesAdmin, so the application needs to
+ * downcast the facet to this type in order to register the callback.
+ *
+ * For example:
+ *
+ * \code
+ * Ice::ObjectPtr obj = communicator->findAdminFacet("Properties");
+ * assert(obj); // May be null if the facet is not enabled
+ * NativePropertiesAdminPtr facet = NativePropertiesAdminPtr::dynamicCast(obj);
+ * PropertiesAdminUpdateCallbackPtr myCallback = ...;
+ * facet->addUpdateCallback(myCallback);
+ * \endcode
+ *
+ * Ice ignores any exceptions raised by the callback.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API PropertiesAdminUpdateCallback : public virtual Ice::LocalObject
 {
 public:
 
     virtual ~PropertiesAdminUpdateCallback();
 
-    virtual void updated(const PropertyDict&) = 0;
+    /**
+     * Called when the communicator's properties have been updated.
+     * @param d A dictionary containing the properties that were added, changed or removed,
+     * with a removed property denoted by an entry whose value is an empty string.
+     */
+    virtual void updated(const PropertyDict& d) = 0;
 };
 typedef IceUtil::Handle<PropertiesAdminUpdateCallback> PropertiesAdminUpdateCallbackPtr;
 #endif
 
+/**
+ * Base class for the Properties admin facet.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API NativePropertiesAdmin
 #ifndef ICE_CPP11_MAPPING
     : public virtual IceUtil::Shared
@@ -55,10 +66,22 @@ public:
     virtual ~NativePropertiesAdmin();
 
 #ifdef ICE_CPP11_MAPPING
-    virtual std::function<void()> addUpdateCallback(std::function<void(const PropertyDict&)>) = 0;
+    /**
+     * Register an update callback that will be invoked when property updates occur.
+     * @param cb The callback.
+     */
+    virtual std::function<void()> addUpdateCallback(std::function<void(const PropertyDict&)> cb) = 0;
 #else
-    virtual void addUpdateCallback(const PropertiesAdminUpdateCallbackPtr&) = 0;
-    virtual void removeUpdateCallback(const PropertiesAdminUpdateCallbackPtr&) = 0;
+    /**
+     * Register an update callback that will be invoked when property updates occur.
+     * @param cb The callback.
+     */
+    virtual void addUpdateCallback(const PropertiesAdminUpdateCallbackPtr& cb) = 0;
+    /**
+     * Remove an update callback.
+     * @param cb The callback to be removed.
+     */
+    virtual void removeUpdateCallback(const PropertiesAdminUpdateCallbackPtr& cb) = 0;
 #endif
 };
 ICE_DEFINE_PTR(NativePropertiesAdminPtr, NativePropertiesAdmin);

data/ext/ice/cpp/include/Ice/Object.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -39,68 +39,161 @@ class GCVisitor;
 namespace Ice
 {
 
+/** A default-initialized Current instance. */
 ICE_API extern const Current emptyCurrent;
 
 #ifndef ICE_CPP11_MAPPING
+/**
+ * Abstract callback class for an asynchronous dispatch interceptor.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API DispatchInterceptorAsyncCallback : public virtual IceUtil::Shared
 {
 public:
 
     virtual ~DispatchInterceptorAsyncCallback();
 
+    /** Called when the dispatch completes successfully. */
     virtual bool response() = 0;
-    virtual bool exception(const std::exception&) = 0;
+
+    /**
+     * Called when the dispatch fails with an exception.
+     * @param ex The exception that caused the failure.
+     */
+    virtual bool exception(const std::exception& ex) = 0;
+
+    /**
+     * Called when the dispatch fails with an unknown exception.
+     */
     virtual bool exception() = 0;
 };
 ICE_DEFINE_PTR(DispatchInterceptorAsyncCallbackPtr, DispatchInterceptorAsyncCallback);
 #endif
 
+/**
+ * Encapsulates details about a dispatch request.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Request
 {
 public:
 
     virtual ~Request();
+
+    /**
+     * Obtains the Current object associated with the request.
+     * @return The Current object.
+     */
     virtual const Current& getCurrent() = 0;
 };
 
 #ifdef ICE_CPP11_MAPPING
+/**
+ * The base class for servants.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Object
 {
 public:
 
     virtual ~Object() = default;
 
-    virtual bool ice_isA(std::string, const Current&) const;
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     * @param s The type ID of the Slice interface to test against.
+     * @param current The Current object for the invocation.
+     * @return True if this object has the interface
+     * specified by s or derives from the interface
+     * specified by s.
+     */
+    virtual bool ice_isA(std::string s, const Current& current) const;
+    /// \cond INTERNAL
     bool _iceD_ice_isA(IceInternal::Incoming&, const Current&);
-
-    virtual void ice_ping(const Current&) const;
+    /// \endcond
+
+    /**
+     * Tests whether this object can be reached.
+     * @param current The Current object for the invocation.
+     */
+    virtual void ice_ping(const Current& current) const;
+    /// \cond INTERNAL
     bool _iceD_ice_ping(IceInternal::Incoming&, const Current&);
-
-    virtual std::vector< std::string> ice_ids(const Current&) const;
+    /// \endcond
+
+    /**
+     * Returns the Slice type IDs of the interfaces supported by this object.
+     * @param current The Current object for the invocation.
+     * @return The Slice type IDs of the interfaces supported by this object, in base-to-derived
+     * order. The first element of the returned array is always "::Ice::Object".
+     */
+    virtual std::vector< std::string> ice_ids(const Current& current) const;
+    /// \cond INTERNAL
     bool _iceD_ice_ids(IceInternal::Incoming&, const Current&);
-
-    virtual std::string ice_id(const Current&) const;
+    /// \endcond
+
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     * @param current The Current object for the invocation.
+     * @return The Slice type ID of the most-derived interface.
+     */
+    virtual std::string ice_id(const Current& current) const;
+    /// \cond INTERNAL
     bool _iceD_ice_id(IceInternal::Incoming&, const Current&);
+    /// \endcond
 
+    /**
+     * Obtains the Slice type ID of this type.
+     * @return The return value is always "::Ice::Object".
+     */
     static const std::string& ice_staticId();
 
-    virtual bool ice_dispatch(Ice::Request&,
-                              std::function<bool()> = nullptr,
-                              std::function<bool(std::exception_ptr)> = nullptr);
-
+    /**
+     * Dispatches an invocation to a servant. This method is used by dispatch interceptors to forward an invocation
+     * to a servant (or to another interceptor).
+     * @param request The details of the invocation.
+     * @param response A function that should return true if Ice should send the response to the client. A null
+     * value is equivalent to a function that returns true.
+     * @param error A function that should return true if Ice should send the exception to the client. A null
+     * value is equivalent to a function that returns true.
+     * @return True if the request completed synchronously, false if the request will be completed asynchronously.
+     * @throws UserException A user exception that propagates out of this method will be marshaled as the result.
+     */
+    virtual bool ice_dispatch(Ice::Request& request,
+                              std::function<bool()> response = nullptr,
+                              std::function<bool(std::exception_ptr)> error = nullptr);
+
+    /// \cond INTERNAL
     virtual bool _iceDispatch(IceInternal::Incoming&, const Current&);
+    /// \endcond
 
+    /**
+     * Holds the results of a call to ice_invoke.
+     */
     struct Ice_invokeResult
     {
+        /**
+         * Indicates whether the invocation resulted in success (true) or a user exception (false).
+         */
         bool returnValue;
+
+        /**
+         * Holds an encapsulation of the encoded results. If returnValue is true, this contains the encoded
+         * out parameters. If returnValue is false, this contains the encoded user exception.
+         */
         std::vector<::Ice::Byte> outParams;
     };
 
 protected:
 
+    /// \cond INTERNAL
     static void _iceCheckMode(OperationMode, OperationMode);
+    /// \endcond
 };
 #else
+/**
+ * The base class for servants.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Object  : public virtual IceUtil::Shared
 {
 public:
@@ -108,37 +201,135 @@ public:
     virtual bool operator==(const Object&) const;
     virtual bool operator<(const Object&) const;
 
-    virtual bool ice_isA(const std::string&, const Current& = Ice::emptyCurrent) const;
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     * @param s The type ID of the Slice interface to test against.
+     * @param current The Current object for the invocation.
+     * @return True if this object has the interface
+     * specified by s or derives from the interface
+     * specified by s.
+     */
+    virtual bool ice_isA(const std::string& s, const Current& current = Ice::emptyCurrent) const;
+    /// \cond INTERNAL
     bool _iceD_ice_isA(IceInternal::Incoming&, const Current&);
-
-    virtual void ice_ping(const Current&  = Ice::emptyCurrent) const;
+    /// \endcond
+
+    /**
+     * Tests whether this object can be reached.
+     * @param current The Current object for the invocation.
+     */
+    virtual void ice_ping(const Current& current = Ice::emptyCurrent) const;
+    /// \cond INTERNAL
     bool _iceD_ice_ping(IceInternal::Incoming&, const Current&);
-
-    virtual std::vector< std::string> ice_ids(const Current& = Ice::emptyCurrent) const;
+    /// \endcond
+
+    /**
+     * Returns the Slice type IDs of the interfaces supported by this object.
+     * @param current The Current object for the invocation.
+     * @return The Slice type IDs of the interfaces supported by this object, in base-to-derived
+     * order. The first element of the returned array is always "::Ice::Object".
+     */
+    virtual std::vector< std::string> ice_ids(const Current& current = Ice::emptyCurrent) const;
+    /// \cond INTERNAL
     bool _iceD_ice_ids(IceInternal::Incoming&, const Current&);
-
-    virtual const std::string& ice_id(const Current& = Ice::emptyCurrent) const;
+    /// \endcond
+
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     * @param current The Current object for the invocation.
+     * @return The Slice type ID of the most-derived interface.
+     */
+    virtual const std::string& ice_id(const Current& current = Ice::emptyCurrent) const;
+    /// \cond INTERNAL
     bool _iceD_ice_id(IceInternal::Incoming&, const Current&);
-
-    virtual Int ice_operationAttributes(const std::string&) const;
-
+    /// \endcond
+
+    /**
+     * Returns the Freeze metadata attributes for an operation.
+     *
+     * @param operation The name of the operation.
+     * @return The least significant bit indicates whether the operation is a read
+     * or write operation. If the bit is set, the operation is a write operation.
+     * The expression ice_operationAttributes("op") &amp; 0x1 is true if
+     * the operation has a <code>["freeze:write"]</code> metadata directive.
+     * <p>
+     * The second and third least significant bit indicate the transactional mode
+     * of the operation. The expression <code>ice_operationAttributes("op") &amp; 0x6 &gt;&gt; 1</code>
+     * indicates the transactional mode as follows:
+     * <dl>
+     *   <dt>0</dt>
+     *   <dd><code>["freeze:read:supports"]</code></dd>
+     *   <dt>1</dt>
+     *   <dd><code>["freeze:read:mandatory"]</code> or <code>["freeze:write:mandatory"]</code></dd>
+     *   <dt>2</dt>
+     *   <dd><code>["freeze:read:required"]</code> or <code>["freeze:write:required"]</code></dd>
+     *   <dt>3</dt>
+     *   <dd><code>["freeze:read:never"]</code></dd>
+     * </dl>
+     *
+     * Refer to the Freeze manual for more information on the TransactionalEvictor.
+     */
+    virtual Int ice_operationAttributes(const std::string& operation) const;
+
+    /// \cond STREAM
     virtual void _iceWrite(Ice::OutputStream*) const;
     virtual void _iceRead(Ice::InputStream*);
+    /// \endcond
 
+    /// \cond INTERNAL
     virtual bool _iceGcVisit(IceInternal::GCVisitor&) { return false; }
-    virtual void ice_collectable(bool) { }
-
+    /// \endcond
+
+    /**
+     * Determines whether this object, and by extension the graph of all objects reachable from this object,
+     * are eligible for garbage collection when all external references to the graph have been released.
+     * @param b True if the object is eligible, false otherwise.
+     */
+    virtual void ice_collectable(bool b);
+
+    /**
+     * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass
+     * to override this method in order to validate its data members.
+     */
     virtual void ice_preMarshal();
+
+    /**
+     * The Ice run time invokes this method vafter unmarshaling an object's data members. This allows a
+     * subclass to override this method in order to perform additional initialization.
+     */
     virtual void ice_postUnmarshal();
 
+    /**
+     * Obtains the Slice type ID of this type.
+     * @return The return value is always "::Ice::Object".
+     */
     static const std::string& ice_staticId();
 
+    /**
+     * Returns a shallow copy of the object.
+     * @return The cloned object.
+     */
     virtual ObjectPtr ice_clone() const;
 
+    /**
+     * Obtains the sliced data associated with this instance.
+     * @return The sliced data if the value has a preserved-slice base class and has been sliced during
+     * unmarshaling of the value, nil otherwise.
+     */
     virtual SlicedDataPtr ice_getSlicedData() const;
 
-    virtual bool ice_dispatch(Ice::Request&, const DispatchInterceptorAsyncCallbackPtr& = 0);
+    /**
+     * Dispatches an invocation to a servant. This method is used by dispatch interceptors to forward an invocation
+     * to a servant (or to another interceptor).
+     * @param request The details of the invocation.
+     * @param cb The asynchronous callback object.
+     * @return True if the request completed synchronously, false if the request will be completed asynchronously.
+     * @throws UserException A user exception that propagates out of this method will be marshaled as the result.
+     */
+    virtual bool ice_dispatch(Ice::Request& request, const DispatchInterceptorAsyncCallbackPtr& cb = 0);
+    /// \cond INTERNAL
     virtual bool _iceDispatch(IceInternal::Incoming&, const Current&);
+    /// \endcond
 
 protected:
 
@@ -147,66 +338,166 @@ protected:
 
 protected:
 
+    /// \cond STREAM
     virtual void _iceWriteImpl(Ice::OutputStream*) const {}
     virtual void _iceReadImpl(Ice::InputStream*) {}
+    /// \endcond
 
+    /// \cond INTERNAL
     static void _iceCheckMode(OperationMode, OperationMode);
+    /// \endcond
 };
 #endif
 
+/**
+ * Base class for dynamic dispatch servants. A server application derives a concrete servant class
+ * from Blobject that implements the ice_invoke method.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Blobject : public virtual Object
 {
 public:
 
-    //
-    // Returns true if ok, false if user exception.
-    //
-    virtual bool ice_invoke(ICE_IN(std::vector<Byte>), std::vector<Byte>&, const Current&) = 0;
-
+    /**
+     * Dispatch an incoming request.
+     *
+     * @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
+     * @param outEncaps An encapsulation containing the encoded results for the operation.
+     * @param current The Current object for the invocation.
+     * @return True if the operation completed successfully, in which case outEncaps contains
+     * an encapsulation of the encoded results, or false if the operation raised a user exception,
+     * in which case outEncaps contains an encapsulation of the encoded user exception.
+     * @throws UserException A user exception can be raised directly and the
+     * run time will marshal it.
+     */
+    virtual bool ice_invoke(ICE_IN(std::vector<Byte>) inEncaps, std::vector<Byte>& outEncaps,
+                            const Current& current) = 0;
+
+    /// \cond INTERNAL
     virtual bool _iceDispatch(IceInternal::Incoming&, const Current&);
+    /// \endcond
 };
 
+/**
+ * Base class for dynamic dispatch servants that uses the array mapping. A server application
+ * derives a concrete servant class from Blobject that implements the ice_invoke method.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API BlobjectArray : public virtual Object
 {
 public:
 
-    //
-    // Returns true if ok, false if user exception.
-    //
-    virtual bool ice_invoke(ICE_IN(std::pair<const Byte*, const Byte*>), std::vector<Byte>&, const Current&) = 0;
-
+    /**
+     * Dispatch an incoming request.
+     *
+     * @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
+     * @param outEncaps An encapsulation containing the encoded results for the operation.
+     * @param current The Current object for the invocation.
+     * @return True if the operation completed successfully, in which case outEncaps contains
+     * an encapsulation of the encoded results, or false if the operation raised a user exception,
+     * in which case outEncaps contains an encapsulation of the encoded user exception.
+     * @throws UserException A user exception can be raised directly and the
+     * run time will marshal it.
+     */
+    virtual bool ice_invoke(ICE_IN(std::pair<const Byte*, const Byte*>) inEncaps, std::vector<Byte>& outEncaps,
+                            const Current& current) = 0;
+
+    /// \cond INTERNAL
     virtual bool _iceDispatch(IceInternal::Incoming&, const Current&);
+    /// \endcond
 };
 
+/**
+ * Base class for asynchronous dynamic dispatch servants. A server application derives a concrete
+ * servant class from Blobject that implements the ice_invokeAsync method.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API BlobjectAsync : public virtual Object
 {
 public:
 
 #ifdef ICE_CPP11_MAPPING
-    virtual void ice_invokeAsync(std::vector<Byte>,
-                                 std::function<void(bool, const std::vector<Byte>&)>,
-                                 std::function<void(std::exception_ptr)>,
-                                 const Current&) = 0;
+    /**
+     * Dispatch an incoming request asynchronously.
+     *
+     * @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
+     * @param response A callback the implementation should invoke when the invocation completes
+     * successfully or with a user exception. See the description of Blobject::ice_invoke for
+     * the semantics.
+     * @param error A callback the implementation should invoke when the invocation completes
+     * with an exception.
+     * @param current The Current object for the invocation.
+     * @throws UserException A user exception can be raised directly and the
+     * run time will marshal it.
+     */
+    virtual void ice_invokeAsync(std::vector<Byte> inEncaps,
+                                 std::function<void(bool, const std::vector<Byte>&)> response,
+                                 std::function<void(std::exception_ptr)> error,
+                                 const Current& current) = 0;
 #else
-    virtual void ice_invoke_async(const AMD_Object_ice_invokePtr&, const std::vector<Byte>&, const Current&) = 0;
+    /**
+     * Dispatch an incoming request asynchronously.
+     *
+     * @param cb The callback to invoke when the invocation completes.
+     * @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
+     * @param current The Current object for the invocation.
+     * @throws UserException A user exception can be raised directly and the
+     * run time will marshal it.
+     */
+    virtual void ice_invoke_async(const AMD_Object_ice_invokePtr& cb, const std::vector<Byte>& inEncaps,
+                                  const Current& current) = 0;
 #endif
+
+    /// \cond INTERNAL
     virtual bool _iceDispatch(IceInternal::Incoming&, const Current&);
+    /// \endcond
 };
 
+/**
+ * Base class for asynchronous dynamic dispatch servants that uses the array mapping. A server application
+ * derives a concrete servant class from Blobject that implements the ice_invokeAsync method.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API BlobjectArrayAsync : public virtual Object
 {
 public:
 
 #ifdef ICE_CPP11_MAPPING
-    virtual void ice_invokeAsync(std::pair<const Byte*, const Byte*>,
-                                 std::function<void(bool, const std::pair<const Byte*, const Byte*>&)>,
-                                 std::function<void(std::exception_ptr)>,
-                                 const Current&) = 0;
+    /**
+     * Dispatch an incoming request asynchronously.
+     *
+     * @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
+     * @param response A callback the implementation should invoke when the invocation completes
+     * successfully or with a user exception. See the description of Blobject::ice_invoke for
+     * the semantics.
+     * @param error A callback the implementation should invoke when the invocation completes
+     * with an exception.
+     * @param current The Current object for the invocation.
+     * @throws UserException A user exception can be raised directly and the
+     * run time will marshal it.
+     */
+    virtual void ice_invokeAsync(std::pair<const Byte*, const Byte*> inEncaps,
+                                 std::function<void(bool, const std::pair<const Byte*, const Byte*>&)> response,
+                                 std::function<void(std::exception_ptr)> error,
+                                 const Current& current) = 0;
 #else
-    virtual void ice_invoke_async(const AMD_Object_ice_invokePtr&, const std::pair<const Byte*, const Byte*>&,
-                                  const Current&) = 0;
+    /**
+     * Dispatch an incoming request asynchronously.
+     *
+     * @param cb The callback to invoke when the invocation completes.
+     * @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
+     * @param current The Current object for the invocation.
+     * @throws UserException A user exception can be raised directly and the
+     * run time will marshal it.
+     */
+    virtual void ice_invoke_async(const AMD_Object_ice_invokePtr& cb,
+                                  const std::pair<const Byte*, const Byte*>& inEncaps,
+                                  const Current& current) = 0;
 #endif
+
+    /// \cond INTERNAL
     virtual bool _iceDispatch(IceInternal::Incoming&, const Current&);
+    /// \endcond
 };
 
 }