zeroc-ice 3.7.0 → 3.7.5

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

@@ -1,15 +1,12 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_FUNCTIONAL_H
 #define ICE_FUNCTIONAL_H
 
+#ifndef ICE_CPP11_MAPPING
+
 #include <IceUtil/Functional.h>
 #include <Ice/Handle.h>
 
@@ -21,6 +18,7 @@
 namespace Ice
 {
 
+/// \cond INTERNAL
 template<class R, class T>
 inline ::IceUtilInternal::MemFun<R, T, ICE_INTERNAL_HANDLE<T> >
 memFun(R (T::*p)(void))
@@ -132,7 +130,9 @@ secondConstVoidMemFun1(void (T::*p)(A) const)
 {
     return ::IceUtilInternal::SecondConstVoidMemFun1<K, T, ICE_INTERNAL_HANDLE<T>, A>(p);
 }
+/// \endcond
 
 }
 
+#   endif
 #endif

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_GC_OBJECT_H
 #define ICE_GC_OBJECT_H

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_HANDLE_H
 #define ICE_HANDLE_H

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_ICE_H
 #define ICE_ICE_H

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_ICONV_STRING_CONVERTER
 #define ICE_ICONV_STRING_CONVERTER
@@ -18,13 +13,13 @@
 #ifndef _WIN32
 
 #include <Ice/StringConverter.h>
+#include <IceUtil/StringUtil.h>
 #include <IceUtil/ThreadException.h>
 #include <IceUtil/UndefSysMacros.h>
 
 #include <algorithm>
 #include <iconv.h>
 #include <langinfo.h>
-#include <string.h> // For strerror
 
 #if (defined(__APPLE__) && _LIBICONV_VERSION < 0x010B)
 //
@@ -36,23 +31,50 @@
 namespace Ice
 {
 
+/**
+ * Indicates that Iconv does not support the code.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API IconvInitializationException : public IceUtil::ExceptionHelper<IconvInitializationException>
 {
 public:
 
-    IconvInitializationException(const char*, int, const std::string&);
+    /**
+     * Constructs the exception with a reason. The file and line number are required.
+     * @param file The file name in which the exception was raised, typically __FILE__.
+     * @param line The line number at which the exception was raised, typically __LINE__.
+     * @param reason More detail about the failure.
+     */
+    IconvInitializationException(const char* file, int line, const std::string& reason);
 
 #ifndef ICE_CPP11_COMPILER
     virtual ~IconvInitializationException() throw();
 #endif
 
+    /**
+     * Obtains the Slice type ID of this exception.
+     * @return The fully-scoped type ID.
+     */
     virtual std::string ice_id() const;
-    virtual void ice_print(std::ostream&) const;
+
+    /**
+     * Prints a description of this exception to the given stream.
+     * @param str The output stream.
+     */
+    virtual void ice_print(std::ostream& str) const;
 
 #ifndef ICE_CPP11_MAPPING
+    /**
+     * Polymporphically clones this exception.
+     * @return A shallow copy of this exception.
+     */
     virtual IconvInitializationException* ice_clone() const;
 #endif
 
+    /**
+     * Obtains the reason for the failure.
+     * @return The reason.
+     */
     std::string reason() const;
 
 private:
@@ -245,7 +267,7 @@ IconvStringConverter<charT>::toUTF8(const charT* sourceStart,
 #else
     char* inbuf = reinterpret_cast<char*>(const_cast<charT*>(sourceStart));
 #endif
-    size_t inbytesleft = (sourceEnd - sourceStart) * sizeof(charT);
+    size_t inbytesleft = static_cast<size_t>(sourceEnd - sourceStart) * sizeof(charT);
     char* outbuf  = 0;
 
     size_t count = 0;
@@ -262,9 +284,8 @@ IconvStringConverter<charT>::toUTF8(const charT* sourceStart,
 
     if(count == size_t(-1))
     {
-        throw Ice::IllegalConversionException(__FILE__,
-                                              __LINE__,
-                                              errno != 0 ? strerror(errno) : "Unknown error");
+        throw Ice::IllegalConversionException(__FILE__, __LINE__,
+                                              errno == 0 ? "Unknown error" : IceUtilInternal::errorToString(errno));
     }
     return reinterpret_cast<Ice::Byte*>(outbuf);
 }
@@ -290,7 +311,8 @@ IconvStringConverter<charT>::fromUTF8(const Ice::Byte* sourceStart, const Ice::B
 #else
     char* inbuf = reinterpret_cast<char*>(const_cast<Ice::Byte*>(sourceStart));
 #endif
-    size_t inbytesleft = sourceEnd - sourceStart;
+    assert(sourceEnd > sourceStart);
+    size_t inbytesleft = static_cast<size_t>(sourceEnd - sourceStart);
 
     char* outbuf = 0;
     size_t outbytesleft = 0;
@@ -304,7 +326,7 @@ IconvStringConverter<charT>::fromUTF8(const Ice::Byte* sourceStart, const Ice::B
         size_t bytesused = 0;
         if(outbuf != 0)
         {
-            bytesused = outbuf - reinterpret_cast<const char*>(target.data());
+            bytesused = static_cast<size_t>(outbuf - reinterpret_cast<const char*>(target.data()));
         }
 
         const size_t increment = std::max<size_t>(inbytesleft, 4);
@@ -318,9 +340,8 @@ IconvStringConverter<charT>::fromUTF8(const Ice::Byte* sourceStart, const Ice::B
 
     if(count == size_t(-1))
     {
-        throw Ice::IllegalConversionException(__FILE__,
-                                              __LINE__,
-                                              errno != 0 ? strerror(errno) : "Unknown error");
+        throw Ice::IllegalConversionException(__FILE__,  __LINE__,
+                                              errno == 0 ? "Unknown error" : IceUtilInternal::errorToString(errno));
     }
 
     target.resize(target.size() - (outbytesleft / sizeof(charT)));
@@ -329,6 +350,13 @@ IconvStringConverter<charT>::fromUTF8(const Ice::Byte* sourceStart, const Ice::B
 
 namespace Ice
 {
+
+/**
+ * Creates a string converter for the given code.
+ * @param internalCodeWithDefault The desired code. If empty or not provided, a default code is used.
+ * @return The converter object.
+ * @throws IconvInitializationException If the code is not supported.
+ */
 template<typename charT>
 ICE_HANDLE<IceUtil::BasicStringConverter<charT> >
 createIconvStringConverter(const std::string& internalCodeWithDefault = "")
@@ -342,6 +370,7 @@ createIconvStringConverter(const std::string& internalCodeWithDefault = "")
 
     return ICE_MAKE_SHARED(IceInternal::IconvStringConverter<charT>, internalCode);
 }
+
 }
 
 #endif

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_INCOMING_H
 #define ICE_INCOMING_H
@@ -29,12 +24,24 @@
 namespace Ice
 {
 
+/**
+ * Base class for marshaled result structures, which are generated for operations having the
+ * marshaled-result metadata tag.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API MarshaledResult
 {
 public:
 
-    MarshaledResult(const Current&);
+    /**
+     * The constructor requires the Current object that was passed to the servant.
+     */
+    MarshaledResult(const Current& current);
 
+    /**
+     * Obtains the output stream that is used to marshal the results.
+     * @return The output stream.
+     */
     std::shared_ptr<OutputStream> getOutputStream() const
     {
         return ostr;
@@ -42,6 +49,7 @@ public:
 
 protected:
 
+    /** The output stream used to marshal the results. */
     std::shared_ptr<OutputStream> ostr;
 };
 
@@ -70,7 +78,7 @@ public:
     void exception(const std::string&, bool);
 #if defined(_MSC_VER) && (_MSC_VER == 1500)
     //
-    // COMPILERFIX VC90 get confused with overloads above
+    // COMPILERFIX v90 get confused with overloads above
     // when passing a const char* as first argument.
     //
     void exception(const char* msg, bool amd)
@@ -94,7 +102,7 @@ protected:
 
 #if defined(_MSC_VER) && (_MSC_VER == 1500)
     //
-    // COMPILERFIX VC90 get confused with overloads above
+    // COMPILERFIX v90 get confused with overloads above
     // when passing a const char* as first argument.
     //
     void handleException(const char* msg, bool amd)
@@ -132,6 +140,12 @@ protected:
     DispatchInterceptorCallbacks _interceptorCBs;
 };
 
+// TODO: fix this warning
+#if defined(_MSC_VER) && (_MSC_VER >= 1900)
+#   pragma warning(push)
+#   pragma warning(disable:4239)
+#endif
+
 class ICE_API Incoming : public IncomingBase
 {
 public:
@@ -202,6 +216,10 @@ private:
     IncomingAsyncPtr _inAsync;
 };
 
+#if defined(_MSC_VER) && (_MSC_VER >= 1900)
+#   pragma warning(pop)
+#endif
+
 }
 
 #endif

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_INCOMING_ASYNC_H
 #define ICE_INCOMING_ASYNC_H
@@ -17,13 +12,25 @@
 namespace Ice
 {
 
+/**
+ * Base class for generated AMD callback classes.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API AMDCallback : public Ice::LocalObject
 {
 public:
 
     virtual ~AMDCallback();
 
-    virtual void ice_exception(const ::std::exception&) = 0;
+    /**
+     * Completes the asynchronous request with the given exception.
+     * @param ex The exception that completed the request.
+     */
+    virtual void ice_exception(const ::std::exception& ex) = 0;
+
+    /**
+     * Completes the asynchronous request with an UnknownException.
+     */
     virtual void ice_exception() = 0;
 };
 
@@ -33,6 +40,12 @@ public:
 namespace IceInternal
 {
 
+// TODO: fix this warning
+#if defined(_MSC_VER) && (_MSC_VER >= 1900)
+#   pragma warning(push)
+#   pragma warning(disable:4239)
+#endif
+
 //
 // We need virtual inheritance from AMDCallback, because we use multiple
 // inheritance from Ice::AMDCallback for generated AMD code.
@@ -106,24 +119,48 @@ private:
     const ResponseHandlerPtr _responseHandlerCopy;
 };
 
+#if defined(_MSC_VER) && (_MSC_VER >= 1900)
+#   pragma warning(pop)
+#endif
+
 }
 
 #ifndef ICE_CPP11_MAPPING
 namespace Ice
 {
 
+/**
+ * Base class for the AMD callback for BlobjectAsync::ice_invoke_async.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API AMD_Object_ice_invoke : public virtual Ice::AMDCallback
 {
 public:
 
     virtual ~AMD_Object_ice_invoke();
 
-    virtual void ice_response(bool, const std::vector<Ice::Byte>&) = 0;
-    virtual void ice_response(bool, const std::pair<const Ice::Byte*, const Ice::Byte*>&) = 0;
+    /**
+     * Completes the request.
+     * @param ok True if the request completed successfully, in which case bytes contains an encapsulation
+     * of the marshaled results. False if the request completed with a user exception, in which case bytes
+     * contains an encapsulation of the marshaled user exception.
+     * @param bytes An encapsulation of the results or user exception.
+     */
+    virtual void ice_response(bool ok, const std::vector<Ice::Byte>& bytes) = 0;
+
+    /**
+     * Completes the request.
+     * @param ok True if the request completed successfully, in which case bytes contains an encapsulation
+     * of the marshaled results. False if the request completed with a user exception, in which case bytes
+     * contains an encapsulation of the marshaled user exception.
+     * @param bytes An encapsulation of the results or user exception.
+     */
+    virtual void ice_response(bool ok, const std::pair<const Ice::Byte*, const Ice::Byte*>& bytes) = 0;
 };
 
 }
 
+/// \cond INTERNAL
 namespace IceAsync
 {
 
@@ -143,6 +180,7 @@ public:
 }
 
 }
+/// \endcond
 #endif
 
 #endif

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_INCOMING_ASYNC_F_H
 #define ICE_INCOMING_ASYNC_F_H

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_INITIALIZE_H
 #define ICE_INITIALIZE_H
@@ -32,112 +27,442 @@
 namespace Ice
 {
 
-ICE_API StringSeq argsToStringSeq(int, const char* const[]);
+/**
+ * Converts an argument vector into a string sequence.
+ * @param argc The number of arguments in argv.
+ * @param argv The arguments.
+ * @return A string sequence containing the arguments.
+ */
+ICE_API StringSeq argsToStringSeq(int argc, const char* const argv[]);
 
 #ifdef _WIN32
-ICE_API StringSeq argsToStringSeq(int, const wchar_t* const[]);
+/**
+ * Converts an argument vector into a string sequence.
+ * @param argc The number of arguments in argv.
+ * @param argv The arguments.
+ * @return A string sequence containing the arguments.
+ */
+ICE_API StringSeq argsToStringSeq(int argc, const wchar_t* const argv[]);
 #endif
 
-//
-// This function assumes that the string sequence only contains
-// elements of the argument vector. The function shifts the
-// the argument vector elements so that the vector matches the
-// contents of the sequence.
-//
-ICE_API void stringSeqToArgs(const StringSeq&, int&, const char*[]);
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ * @param argc Updated to reflect the size of the sequence.
+ * @param argv Elements are shifted to match the sequence.
+ */
+ICE_API void stringSeqToArgs(const StringSeq& seq, int& argc, const char* argv[]);
+
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ * @param argc Updated to reflect the size of the sequence.
+ * @param argv Elements are shifted to match the sequence.
+ */
 inline void stringSeqToArgs(const StringSeq& seq, int& argc, char* argv[])
 {
     return stringSeqToArgs(seq, argc, const_cast<const char**>(argv));
 }
 
 #ifdef _WIN32
-ICE_API void stringSeqToArgs(const StringSeq&, int&, const wchar_t*[]);
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ */
+ICE_API void stringSeqToArgs(const StringSeq& seq, int& argc, const wchar_t* argv[]);
+
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ */
 inline void stringSeqToArgs(const StringSeq& seq, int& argc, wchar_t* argv[])
 {
     return stringSeqToArgs(seq, argc, const_cast<const wchar_t**>(argv));
 }
 #endif
 
+/**
+ * Creates a new empty property set.
+ *
+ * @return A new empty property set.
+ */
 ICE_API PropertiesPtr createProperties();
-ICE_API PropertiesPtr createProperties(StringSeq&, const PropertiesPtr& = 0);
-ICE_API PropertiesPtr createProperties(int&, const char*[], const PropertiesPtr& = 0);
-inline PropertiesPtr createProperties(int& argc, char* argv[], const PropertiesPtr& props = 0)
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param seq Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this container upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+ICE_API PropertiesPtr createProperties(StringSeq& seq, const PropertiesPtr& defaults = 0);
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+ICE_API PropertiesPtr createProperties(int& argc, const char* argv[], const PropertiesPtr& defaults = 0);
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+inline PropertiesPtr createProperties(int& argc, char* argv[], const PropertiesPtr& defaults = 0)
 {
-    return createProperties(argc, const_cast<const char**>(argv), props);
+    return createProperties(argc, const_cast<const char**>(argv), defaults);
 }
 
 #ifdef _WIN32
-ICE_API PropertiesPtr createProperties(int&, const wchar_t*[], const PropertiesPtr& = 0);
-inline PropertiesPtr createProperties(int& argc, wchar_t* argv[], const PropertiesPtr& props = 0)
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+ICE_API PropertiesPtr createProperties(int& argc, const wchar_t* argv[], const PropertiesPtr& defaults = 0);
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+inline PropertiesPtr createProperties(int& argc, wchar_t* argv[], const PropertiesPtr& defaults = 0)
 {
-    return createProperties(argc, const_cast<const wchar_t**>(argv), props);
+    return createProperties(argc, const_cast<const wchar_t**>(argv), defaults);
 }
 #endif
 
-//
-// This class is used to notify user of when Ice threads are started
-// and stopped.
-//
+/**
+ * Base class for a thread notification hook. An application can subclass this class,
+ * implement start and stop, and install an instance in InitializationData in order
+ * to receive notifications when Ice threads are started and stopped.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API ThreadNotification : public IceUtil::Shared
 {
 public:
 
+    /**
+     * Called from the new Ice thread at startup.
+     */
     virtual void start() = 0;
+
+    /**
+     * Called from an Ice thread that is about to stop.
+     */
     virtual void stop() = 0;
 };
 
 typedef IceUtil::Handle<ThreadNotification> ThreadNotificationPtr;
 
-//
-// A special plug-in that installs thread hook during a communicator's initialization.
-// Both initialize and destroy are no-op. See Ice::InitializationData.
-//
+/**
+ * A special plug-in that installs a thread hook during a communicator's initialization.
+ * Both initialize and destroy are no-op. See InitializationData.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API ThreadHookPlugin : public Ice::Plugin
 {
 public:
 
 #ifdef ICE_CPP11_MAPPING
-    ThreadHookPlugin(const CommunicatorPtr& communicator, std::function<void()>, std::function<void()>);
+    /**
+     * Installs the thread hooks.
+     * @param communicator The communicator in which to install the thread hooks.
+     * @param start The start callback.
+     * @param stop The stop callback.
+     */
+    ThreadHookPlugin(const CommunicatorPtr& communicator, std::function<void()> start, std::function<void()> stop);
 #else
-    ThreadHookPlugin(const CommunicatorPtr& communicator, const ThreadNotificationPtr&);
+    /**
+     * Installs the thread hooks.
+     * @param communicator The communicator in which to install the thread hooks.
+     * @param hook The thread notification callback object.
+     */
+    ThreadHookPlugin(const CommunicatorPtr& communicator, const ThreadNotificationPtr& hook);
 #endif
+
+    /** Not used. */
     virtual void initialize();
 
+    /** Not used. */
     virtual void destroy();
 };
 
-//
-// Communicator initialization info
-//
+/**
+ * Encapsulates data to initialize a communicator.
+ * \headerfile Ice/Ice.h
+ */
 struct InitializationData
 {
+    /**
+     * The properties for the communicator.
+     */
     PropertiesPtr properties;
+
+    /**
+     * The logger for the communicator.
+     */
     LoggerPtr logger;
+
+    /**
+     * The communicator observer used by the Ice run-time.
+     */
     Instrumentation::CommunicatorObserverPtr observer;
+
 #ifdef ICE_CPP11_MAPPING
+
+#if defined(__clang__)
+#   pragma clang diagnostic push
+#   pragma clang diagnostic ignored "-Wdocumentation" // param/return is not recognized for std::function data members
+#endif
+
+    /**
+     * Called whenever the communicator starts a new thread.
+     */
     std::function<void()> threadStart;
+
+    /**
+     * Called whenever a thread created by the communicator is about to be destroyed.
+     */
     std::function<void()> threadStop;
-    std::function<void(std::function<void()>, const std::shared_ptr<Ice::Connection>&)> dispatcher;
-    std::function<std::string(int)> compactIdResolver;
-    std::function<void(const Ice::BatchRequest&, int, int)> batchRequestInterceptor;
+
+    /**
+      * You can control which thread receives operation invocations and AMI
+      * callbacks by supplying a dispatcher.
+      *
+      * For example, you can use this dispatching facility to ensure that
+      * all invocations and callbacks are dispatched in a GUI event loop
+      * thread so that it is safe to invoke directly on GUI objects.
+      *
+      * The dispatcher is responsible for running (dispatching) the
+      * invocation or AMI callback on its favorite thread.
+      * @param call Represents the invocation. The dispatcher must eventually invoke this function.
+      * @param con The connection associated with this dispatch, or nil if no connection is
+      * associated with it.
+      */
+    std::function<void(std::function<void()> call, const std::shared_ptr<Ice::Connection>& con)> dispatcher;
+
+    /**
+     * Applications that make use of compact type IDs to conserve space
+     * when marshaling class instances, and also use the streaming API to
+     * extract such classes, can intercept the translation between compact
+     * type IDs and their corresponding string type IDs by installing a
+     * compact ID resolver.
+     * @param id The compact ID.
+     * @return The fully-scoped type ID such as "::Module::Class", or an empty string if
+     * the compact ID is unknown.
+     */
+    std::function<std::string(int id)> compactIdResolver;
+
+    /**
+     * The batch request interceptor, which is called by the Ice run time to enqueue a batch request.
+     * @param req An object representing the batch request.
+     * @param count The number of requests currently in the queue.
+     * @param size The number of bytes consumed by the requests currently in the queue.
+     */
+    std::function<void(const Ice::BatchRequest& req, int count, int size)> batchRequestInterceptor;
+
+#if defined(__clang__)
+#   pragma clang diagnostic pop
+#endif
+
 #else
+    /**
+     * The thread hook for the communicator.
+     */
     ThreadNotificationPtr threadHook;
+
+    /**
+      * You can control which thread receives operation invocations and AMI
+      * callbacks by supplying a dispatcher.
+      *
+      * For example, you can use this dispatching facility to ensure that
+      * all invocations and callbacks are dispatched in a GUI event loop
+      * thread so that it is safe to invoke directly on GUI objects.
+      *
+      * The dispatcher is responsible for running (dispatching) the
+      * invocation or AMI callback on its favorite thread. It must eventually
+      * execute the provided call.
+      */
     DispatcherPtr dispatcher;
+
+    /**
+     * Applications that make use of compact type IDs to conserve space
+     * when marshaling class instances, and also use the streaming API to
+     * extract such classes, can intercept the translation between compact
+     * type IDs and their corresponding string type IDs by installing a
+     * compact ID resolver.
+     */
     CompactIdResolverPtr compactIdResolver;
+
+    /**
+     * The batch request interceptor.
+     */
     BatchRequestInterceptorPtr batchRequestInterceptor;
 #endif
+
+    /**
+     * The value factory manager.
+     */
     ValueFactoryManagerPtr valueFactoryManager;
 };
 
-ICE_API CommunicatorPtr initialize(int&, const char*[], const InitializationData& = InitializationData(),
-                                   int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const char* argv[],
+                                   const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
 inline CommunicatorPtr initialize(int& argc, char* argv[], const InitializationData& initData = InitializationData(),
                                    int version = ICE_INT_VERSION)
 {
     return initialize(argc, const_cast<const char**>(argv), initData, version);
 }
 
-ICE_API CommunicatorPtr initialize(int&, const char*[], ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const char* argv[], ICE_CONFIG_FILE_STRING configFile,
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
 inline CommunicatorPtr initialize(int& argc, char* argv[], ICE_CONFIG_FILE_STRING configFile,
                                   int version = ICE_INT_VERSION)
 {
@@ -145,15 +470,79 @@ inline CommunicatorPtr initialize(int& argc, char* argv[], ICE_CONFIG_FILE_STRIN
 }
 
 #ifdef _WIN32
-ICE_API CommunicatorPtr initialize(int&, const wchar_t*[], const InitializationData& = InitializationData(),
-                                   int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const wchar_t* argv[],
+                                   const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
 inline CommunicatorPtr initialize(int& argc, wchar_t* argv[], const InitializationData& initData = InitializationData(),
                                    int version = ICE_INT_VERSION)
 {
     return initialize(argc, const_cast<const wchar_t**>(argv), initData, version);
 }
 
-ICE_API CommunicatorPtr initialize(int&, const wchar_t*[], ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const wchar_t* argv[], ICE_CONFIG_FILE_STRING configFile,
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
 inline CommunicatorPtr initialize(int& argc, wchar_t* argv[], ICE_CONFIG_FILE_STRING configFile,
                                   int version = ICE_INT_VERSION)
 {
@@ -161,102 +550,373 @@ inline CommunicatorPtr initialize(int& argc, wchar_t* argv[], ICE_CONFIG_FILE_ST
 }
 #endif
 
-ICE_API CommunicatorPtr initialize(StringSeq&, const InitializationData& = InitializationData(),
-                                   int = ICE_INT_VERSION);
-
-ICE_API CommunicatorPtr initialize(StringSeq&, ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
-
-ICE_API CommunicatorPtr initialize(const InitializationData& = InitializationData(),
-                                   int = ICE_INT_VERSION);
-
-ICE_API CommunicatorPtr initialize(ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
-
+/**
+ * Initializes a new communicator.
+ * @param seq Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this container upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(StringSeq& seq, const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param seq Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this container upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(StringSeq& seq, ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
+
+/**
+ * Obtains the per-process logger. This logger is used by all communicators that do not have their
+ * own specific logger established at the time a communicator is created.
+ * @return The current per-process logger instance.
+ */
 ICE_API LoggerPtr getProcessLogger();
-ICE_API void setProcessLogger(const LoggerPtr&);
 
-typedef Ice::Plugin* (*PluginFactory)(const ::Ice::CommunicatorPtr&, const std::string&, const ::Ice::StringSeq&);
-ICE_API void registerPluginFactory(const std::string&, PluginFactory, bool);
-
-//
-// RAII helper class
-//
+/**
+ * Sets the per-process logger. This logger is used by all communicators that do not have their
+ * own specific logger established at the time a communicator is created.
+ * @param logger The new per-process logger instance.
+ */
+ICE_API void setProcessLogger(const LoggerPtr& logger);
+
+/**
+ * A plug-in factory function is responsible for creating an Ice plug-in.
+ * @param communicator The communicator in which the plug-in will be installed.
+ * @param name The name assigned to the plug-in.
+ * @param args Additional arguments included in the plug-in's configuration.
+ * @return The new plug-in object. Returning nil will cause the run time to raise PluginInitializationException.
+ */
+typedef Ice::Plugin* (*PluginFactory)(const ::Ice::CommunicatorPtr& communicator, const std::string& name,
+                                      const ::Ice::StringSeq& args);
+
+/**
+ * Manually registers a plug-in factory function.
+ * @param name The name assigned to the plug-in.
+ * @param factory The factory function.
+ * @param loadOnInit If true, the plug-in is always loaded (created) during communicator initialization,
+ * even if Ice.Plugin.name is not set. When false, the plug-in is loaded (created) during communication
+ * initialization only if Ice.Plugin.name  is set to a non-empty value (e.g.: Ice.Plugin.IceSSL=1).
+ */
+ICE_API void registerPluginFactory(const std::string& name, PluginFactory factory, bool loadOnInit);
+
+/**
+ * A helper class that uses Resource Acquisition Is Initialization (RAII) to initialize and hold a
+ * communicator instance, and automatically destroy the communicator when the holder goes out of scope.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API CommunicatorHolder
 {
 public:
 
-    //
-    // Empty holder
-    //
+    /**
+     * The holder's initial state is empty.
+     */
     CommunicatorHolder();
 
 #ifdef ICE_CPP11_MAPPING
 
-    //
-    // Call initialize to create communicator with the provided args
-    // (all except default ctor above)
-    //
-    //
+    /**
+     * Calls initialize to create a communicator with the provided arguments.
+     * This constructor accepts all of the same overloaded argument styles as
+     * initialize.
+     */
     template<class... T>
     explicit CommunicatorHolder(T&&... args) :
         _communicator(std::move(initialize(std::forward<T>(args)...)))
     {
     }
 
-    //
-    // Adopt communicator
-    //
-    explicit CommunicatorHolder(std::shared_ptr<Communicator>);
-    CommunicatorHolder& operator=(std::shared_ptr<Communicator>);
+    /**
+     * Adopts the given communicator.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder(std::shared_ptr<Communicator> communicator);
 
-    CommunicatorHolder(const CommunicatorHolder&) = delete;
+    /**
+     * Adopts the given communicator. If this holder currently holds a communicator,
+     * it will be destroyed.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder& operator=(std::shared_ptr<Communicator> communicator);
 
+    CommunicatorHolder(const CommunicatorHolder&) = delete;
     CommunicatorHolder(CommunicatorHolder&&) = default;
-    CommunicatorHolder& operator=(CommunicatorHolder&&);
 
+    /**
+     * Adopts the communicator in the given holder. If this holder currently holds a communicator,
+     * it will be destroyed.
+     * @param holder The holder from which to adopt a communicator.
+     */
+    CommunicatorHolder& operator=(CommunicatorHolder&& holder) noexcept;
+
+    /**
+     * Determines whether the holder contains an instance.
+     * @return True if the holder currently holds an instance, false otherwise.
+     */
     explicit operator bool() const;
 
 #else // C++98 mapping
 
-    //
-    // Call initialize to create communicator with the provided args
-    //
-    CommunicatorHolder(int&, const char*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
-    CommunicatorHolder(int&, char*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
-    CommunicatorHolder(int&, const char*[], const char*, int = ICE_INT_VERSION);
-    CommunicatorHolder(int&, char*[], const char*, int = ICE_INT_VERSION);
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const char* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, char* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const char* argv[], const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, char* argv[], const char* configFile, int version = ICE_INT_VERSION);
 
 #   ifdef _WIN32
-    CommunicatorHolder(int&, const wchar_t*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
-    CommunicatorHolder(int&, wchar_t*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
-    CommunicatorHolder(int&, const wchar_t*[], const char*, int = ICE_INT_VERSION);
-    CommunicatorHolder(int&, wchar_t*[], const char*, int = ICE_INT_VERSION);
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const wchar_t* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, wchar_t* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const wchar_t* argv[], const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, wchar_t* argv[], const char* configFile, int version = ICE_INT_VERSION);
 #   endif
 
-    explicit CommunicatorHolder(StringSeq&, const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
-    CommunicatorHolder(StringSeq&, const char*, int = ICE_INT_VERSION);
-
-    explicit CommunicatorHolder(const InitializationData&, int = ICE_INT_VERSION);
-    explicit CommunicatorHolder(const char*, int = ICE_INT_VERSION);
-
-    //
-    // Adopt communicator
-    //
-    explicit CommunicatorHolder(const CommunicatorPtr&);
-    CommunicatorHolder& operator=(const CommunicatorPtr&);
-
+    /**
+     * Initializes a new communicator.
+     * @param seq Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this container upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    explicit CommunicatorHolder(StringSeq& seq, const InitializationData& initData = InitializationData(),
+                                int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param seq Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this container upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(StringSeq& seq, const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    explicit CommunicatorHolder(const InitializationData& initData, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    explicit CommunicatorHolder(const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Adopts the given communicator.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder(const CommunicatorPtr& communicator);
+
+    /**
+     * Adopts the given communicator. If this holder currently holds a communicator,
+     * it will be destroyed.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder& operator=(const CommunicatorPtr& communicator);
+
+    /**
+     * Determines whether the holder contains an instance.
+     * @return True if the holder currently holds an instance, false otherwise.
+     */
     operator bool() const;
 
+    /// \cond INTERNAL
     //
     // Required for successful copy-initialization, but not
-    // defined as it should always be elided by compiler
+    // defined as it should always be elided by the compiler.
     CommunicatorHolder(const CommunicatorHolder&);
+    /// \endcond
 
 #endif
 
     ~CommunicatorHolder();
 
+    /**
+     * Obtains the communicator instance.
+     * @return The communicator held by this holder, or nil if the holder is empty.
+     */
     const CommunicatorPtr& communicator() const;
+
+    /**
+     * Obtains the communicator instance.
+     * @return The communicator held by this holder, or nil if the holder is empty.
+     */
     const CommunicatorPtr& operator->() const;
+
+    /**
+     * Obtains the communicator instance and clears the reference held by the holder.
+     * @return The communicator held by this holder, or nil if the holder is empty.
+     */
     CommunicatorPtr release();
 
 private:
@@ -264,8 +924,20 @@ private:
     CommunicatorPtr  _communicator;
 };
 
-ICE_API Identity stringToIdentity(const std::string&);
-ICE_API std::string identityToString(const Identity&, ToStringMode = ICE_ENUM(ToStringMode, Unicode));
+/**
+ * Converts a stringified identity into an Identity.
+ * @param str The stringified identity.
+ * @return An Identity structure containing the name and category components.
+ */
+ICE_API Identity stringToIdentity(const std::string& str);
+
+/**
+ * Converts an Identity structure into a string using the specified mode.
+ * @param id The identity structure.
+ * @param mode Affects the handling of non-ASCII characters and non-printable ASCII characters.
+ * @return The stringified identity.
+ */
+ICE_API std::string identityToString(const Identity& id, ToStringMode mode = ICE_ENUM(ToStringMode, Unicode));
 
 }