zeroc-ice 3.7.0 → 3.7.1

data/ext/ice/cpp/include/Ice/ExceptionHelpers.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.
@@ -20,24 +20,40 @@ namespace Ice
 
 class LocalException;
 
+/**
+ * Helper template for local exceptions.
+ * \headerfile Ice/Ice.h
+ */
 template<typename T, typename B> class LocalExceptionHelper : public IceUtil::ExceptionHelper<T, B>
 {
 public:
 
     using IceUtil::ExceptionHelper<T, B>::ExceptionHelper;
 
+    /**
+     * Obtains the Slice type ID of this exception.
+     * @return The fully-scoped type ID.
+     */
     virtual std::string ice_id() const override
     {
         return T::ice_staticId();
     }
 };
 
+/**
+ * Helper template for user exceptions.
+ * \headerfile Ice/Ice.h
+ */
 template<typename T, typename B> class UserExceptionHelper : public IceUtil::ExceptionHelper<T, B>
 {
 public:
 
     using IceUtil::ExceptionHelper<T, B>::ExceptionHelper;
 
+    /**
+     * Obtains the Slice type ID of this exception.
+     * @return The fully-scoped type ID.
+     */
     virtual std::string ice_id() const override
     {
         return T::ice_staticId();
@@ -45,6 +61,7 @@ public:
 
 protected:
 
+    /// \cond STREAM
     virtual void _writeImpl(Ice::OutputStream* os) const override
     {
         os->startSlice(T::ice_staticId(), -1, std::is_same<B, Ice::LocalException>::value ? true : false);
@@ -60,6 +77,7 @@ protected:
         is->endSlice();
         B::_readImpl(is);
     }
+    /// \endcond
 };
 
 }

data/ext/ice/cpp/include/Ice/FactoryTable.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.
@@ -17,11 +17,21 @@
 namespace Ice
 {
 
+/**
+ * The base class for a compact ID resolver. Subclasses must implement resolve.
+ * The resolver can be installed via InitializationData.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API CompactIdResolver : public IceUtil::Shared
 {
 public:
 
-    virtual ::std::string resolve(Ice::Int) const = 0;
+    /**
+     * Called by the Ice run time when a compact ID must be translated into a type ID.
+     * @param id The compact ID.
+     * @return The fully-scoped Slice type ID, or an empty string if the compact ID is unknown.
+     */
+    virtual ::std::string resolve(Ice::Int id) const = 0;
 };
 typedef IceUtil::Handle<CompactIdResolver> CompactIdResolverPtr;
 

data/ext/ice/cpp/include/Ice/FactoryTableInit.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/Format.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,27 +15,26 @@
 namespace Ice
 {
 
-//
-// This enumeration describes the possible formats for classes and exceptions.
-//
-
+/**
+ * Describes the possible formats for classes and exceptions.
+ */
 #ifdef ICE_CPP11_MAPPING
 enum class FormatType : unsigned char
 #else
 enum FormatType
 #endif
 {
-    //
-    // Indicates that no preference was specified.
-    //
+    /**
+     * Indicates that no preference was specified.
+     */
     DefaultFormat,
-    //
-    // A minimal format that eliminates the possibility for slicing unrecognized types.
-    //
+    /**
+     * A minimal format that eliminates the possibility for slicing unrecognized types.
+     */
     CompactFormat,
-    //
-    // Allow slicing and preserve slices for unknown types.
-    //
+    /**
+     * Allow slicing and preserve slices for unknown types.
+     */
     SlicedFormat
 };
 

data/ext/ice/cpp/include/Ice/Functional.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.
@@ -10,6 +10,8 @@
 #ifndef ICE_FUNCTIONAL_H
 #define ICE_FUNCTIONAL_H
 
+#   if !defined(ICE_CPP11_MAPPING) || defined(ICE_BUILDING_SRC)
+
 #include <IceUtil/Functional.h>
 #include <Ice/Handle.h>
 
@@ -21,6 +23,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 +135,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,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/Handle.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/Ice.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/IconvStringConverter.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,23 +36,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:
@@ -329,6 +356,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 +376,7 @@ createIconvStringConverter(const std::string& internalCodeWithDefault = "")
 
     return ICE_MAKE_SHARED(IceInternal::IconvStringConverter<charT>, internalCode);
 }
+
 }
 
 #endif

data/ext/ice/cpp/include/Ice/Incoming.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.
@@ -29,12 +29,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 +54,7 @@ public:
 
 protected:
 
+    /** The output stream used to marshal the results. */
     std::shared_ptr<OutputStream> ostr;
 };
 

data/ext/ice/cpp/include/Ice/IncomingAsync.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.
@@ -17,13 +17,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;
 };
 
@@ -112,18 +124,38 @@ private:
 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 +175,7 @@ public:
 }
 
 }
+/// \endcond
 #endif
 
 #endif

data/ext/ice/cpp/include/Ice/IncomingAsyncF.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/Initialize.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.
@@ -32,112 +32,431 @@
 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
+    /**
+     * 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;
 #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 +464,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 +544,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);
+
+    /**
+     * 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 +918,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));
 
 }