zeroc-ice 3.7.0 → 3.7.1

data/ext/ice/cpp/include/Ice/StringConverter.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,34 +17,65 @@
 namespace Ice
 {
 
+/** Encapsulates bytes in the UTF-8 encoding. */
 typedef IceUtil::UTF8Buffer UTF8Buffer;
+
+/** Narrow string converter. */
 typedef IceUtil::StringConverter StringConverter;
 typedef IceUtil::StringConverterPtr StringConverterPtr;
+
+/** Wide string converter. */
 typedef IceUtil::WstringConverter WstringConverter;
 typedef IceUtil::WstringConverterPtr WstringConverterPtr;
 
+/** Indicates an error occurred during string conversion. */
 typedef IceUtil::IllegalConversionException IllegalConversionException;
 
 #ifdef ICE_CPP11_MAPPING
+/** Base class for a string converter. */
 template<typename charT>
 using BasicStringConverter = IceUtil::BasicStringConverter<charT>;
 #endif
 
 #ifdef _WIN32
+/**
+ * Creates a string converter that converts between multi-byte and UTF-8 strings and uses MultiByteToWideChar
+ * and WideCharToMultiByte for its implementation.
+ */
 using IceUtil::createWindowsStringConverter;
 #endif
 
+/** Creates a string converter that converts between Unicode wide strings and UTF-8 strings. */
 using IceUtil::createUnicodeWstringConverter;
 
+/** Installs a default narrow string converter for the process. */
 using IceUtil::setProcessStringConverter;
+
+/** Obtains the default narrow string converter for the process. */
 using IceUtil::getProcessStringConverter;
+
+/** Installs a default wide string converter for the process. */
 using IceUtil::setProcessWstringConverter;
+
+/** Obtains the default wide string converter for the process. */
 using IceUtil::getProcessWstringConverter;
 
+/** Converts a wide string to a narrow string. */
 using IceUtil::wstringToString;
+
+/** Converts a narrow string to a wide string. */
 using IceUtil::stringToWstring;
 
+/**
+ * Converts a narrow string to a UTF-8 encoded string using a string converter.
+ * No conversion is performed if the string converter is nil.
+ */
 using IceUtil::nativeToUTF8;
+
+/**
+ * Converts a UTF-8 encoded string to a narrow string using a string converter.
+ * No conversion is performed if the string converter is nil.
+ */
 using IceUtil::UTF8ToNative;
 
 }

data/ext/ice/cpp/include/Ice/ThreadPoolF.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/UUID.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.
@@ -16,6 +16,7 @@
 namespace Ice
 {
 
+/** Generates a UUID. */
 using IceUtil::generateUUID;
 
 }

data/ext/ice/cpp/include/Ice/UniquePtr.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.
@@ -95,6 +95,6 @@ private:
 
 #endif
 
-} // End of namespace IceUtil
+}
 
 #endif

data/ext/ice/cpp/include/Ice/UniqueRef.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.
@@ -47,7 +47,11 @@ public:
 
     void reset(R ref = 0)
     {
-        assert(ref == 0 || ref != _ref);
+        //
+        // Support "self-reset" for CF objects. This is useful if CF allocation methods return
+        // the same object with an increased reference count.
+        //
+        //assert(ref == 0 || ref != _ref);
 
         if(_ref != 0)
         {

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

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -19,6 +19,7 @@
 namespace Ice
 {
 
+/** Creates and throws a user exception. */
 using UserExceptionFactory = std::function<void(const std::string&)>;
 
 }
@@ -44,6 +45,10 @@ defaultUserExceptionFactory(const std::string& typeId)
 namespace Ice
 {
 
+/**
+ * Creates and throws a user exception.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API UserExceptionFactory : public IceUtil::Shared
 {
 public:

data/ext/ice/cpp/include/Ice/Value.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.
@@ -21,6 +21,10 @@
 namespace Ice
 {
 
+/**
+ * The base class for instances of Slice classes.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Value
 {
 public:
@@ -36,26 +40,61 @@ public:
     Value& operator=(Value&&) = default;
     virtual ~Value() = default;
 
+    /**
+     * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass
+     * to override this method in order to validate its data members.
+     */
     virtual void ice_preMarshal();
+
+    /**
+     * The Ice run time invokes this method vafter unmarshaling an object's data members. This allows a
+     * subclass to override this method in order to perform additional initialization.
+     */
     virtual void ice_postUnmarshal();
 
+    /**
+     * Obtains the Slice type ID of the most-derived class supported by this object.
+     * @return The type ID.
+     */
     virtual std::string ice_id() const;
+
+    /**
+     * Obtains the Slice type ID of this type.
+     * @return The return value is always "::Ice::Object".
+     */
     static const std::string& ice_staticId();
 
+    /**
+     * Returns a shallow copy of the object.
+     * @return The cloned value.
+     */
     std::shared_ptr<Value> ice_clone() const;
 
+    /**
+     * Obtains the sliced data associated with this instance.
+     * @return The sliced data if the value has a preserved-slice base class and has been sliced during
+     * unmarshaling of the value, nil otherwise.
+     */
     virtual std::shared_ptr<SlicedData> ice_getSlicedData() const;
 
+    /// \cond STREAM
     virtual void _iceWrite(Ice::OutputStream*) const;
     virtual void _iceRead(Ice::InputStream*);
+    /// \endcond
 
 protected:
 
+    /// \cond INTERNAL
     virtual std::shared_ptr<Value> _iceCloneImpl() const = 0;
+    /// \endcond
+
+    /// \cond STREAM
     virtual void _iceWriteImpl(Ice::OutputStream*) const {}
     virtual void _iceReadImpl(Ice::InputStream*) {}
+    /// \endcond
 };
 
+/// \cond INTERNAL
 template<typename T, typename Base> class ValueHelper : public Base
 {
 public:
@@ -97,6 +136,7 @@ protected:
         Base::_iceReadImpl(is);
     }
 };
+/// \endcond
 
 }
 #endif // C++11 mapping end

data/ext/ice/cpp/include/Ice/ValueF.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,7 +17,9 @@ namespace Ice
 {
 
 class Value;
+/// \cond INTERNAL
 using ValuePtr = ::std::shared_ptr<Value>;
+/// \endcond
 
 }
 #endif

data/ext/ice/cpp/include/IceSSL/Config.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/IceSSL/IceSSL.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/IceSSL/OpenSSL.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.
@@ -43,7 +43,14 @@
 namespace Ice
 {
 
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSLOpenSSL(bool = true);
+/**
+ * When using static libraries, calling this function ensures the OpenSSL version of the IceSSL plug-in is
+ * linked with the application.
+ * @param loadOnInitialize If true, the plug-in is loaded (created) during communicator initialization.
+ * If false, the plug-in is only loaded during communicator initialization if its corresponding plug-in
+ * property is set to 1.
+ */
+ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSLOpenSSL(bool loadOnInitialize = true);
 
 }
 #endif
@@ -57,69 +64,84 @@ namespace OpenSSL
 class Certificate;
 ICE_DEFINE_PTR(CertificatePtr, Certificate);
 
+/**
+ * Encapsulates an OpenSSL X.509 certificate.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_OPENSSL_API Certificate : public virtual IceSSL::Certificate
 {
 public:
 
-    //
-    // Construct a certificate using a native certificate.
-    //
-    // The Certificate class assumes ownership of the given native
-    // certificate.
-    //
-    static CertificatePtr create(x509_st*);
-
-    //
-    // Load the certificate from a file. The certificate must use the
-    // PEM encoding format. Raises CertificateReadException if the
-    // file cannot be read.
-    //
-    static CertificatePtr load(const std::string&);
-
-    //
-    // Decode a certificate from a string that uses the PEM encoding
-    // format. Raises CertificateEncodingException if an error
-    // occurs.
-    //
-    static CertificatePtr decode(const std::string&);
-
-    //
-    // Retrieve the native X509 certificate value wrapped by this
-    // object.
-    //
-    // The returned reference is only valid for the lifetime of this
-    // object. you can increment it with X509_dup.
-    //
+    /**
+     * Construct a certificate using a native certificate.
+     * The Certificate class assumes ownership of the given native
+     * certificate.
+     * @param cert The native certificate.
+     * @return A new certificate object.
+     */
+    static CertificatePtr create(x509_st* cert);
+
+    /**
+     * Load the certificate from a file. The certificate must use the
+     * PEM encoding format.
+     * @param file The certificate file.
+     * @return A new certificate object.
+     * @throws CertificateReadException if the file cannot be read.
+     */
+    static CertificatePtr load(const std::string& file);
+
+    /**
+     * Decode a certificate from a string that uses the PEM encoding format.
+     * @param cert A string containing the PEM-encoded certificate.
+     * @return A new certificate object.
+     * @throws CertificateEncodingException if an error occurs.
+     */
+    static CertificatePtr decode(const std::string& cert);
+
+    /**
+     * Retrieve the native X509 certificate value wrapped by this object.
+     * @return The native certificate. The returned reference is only valid for the lifetime of this
+     * object. You can increment it with X509_dup.
+     */
     virtual x509_st* getCert() const = 0;
 };
 
+/**
+ * Represents the IceSSL plug-in object.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_OPENSSL_API Plugin : public virtual IceSSL::Plugin
 {
 public:
-    //
-    // returns OpenSSL version number.
-    //
+
+    /**
+     * Obtains the OpenSSL version number.
+     * @return The version.
+     */
     virtual Ice::Long getOpenSSLVersion() const = 0;
-    //
-    // Establish the OpenSSL context. This must be done before the
-    // plug-in is initialized, therefore the application must define
-    // the property Ice.InitPlugins=0, set the context, and finally
-    // invoke initializePlugins on the PluginManager.
-    //
-    // When the application supplies its own OpenSSL context, the
-    // plug-in ignores configuration properties related to certificates,
-    // keys, and passwords.
-    //
-    // Note that the plugin assumes ownership of the given context.
-    //
-    virtual void setContext(SSL_CTX*) = 0;
-
-    //
-    // Obtain the SSL context. Use caution when modifying this value.
-    // Changes made to this value have no effect on existing connections.
-    //
-    virtual SSL_CTX* getContext() = 0;
 
+    /**
+     * Establishes the OpenSSL context. This must be done before the
+     * plug-in is initialized, therefore the application must define
+     * the property Ice.InitPlugins=0, set the context, and finally
+     * invoke Ice::PluginManager::initializePlugins.
+     *
+     * When the application supplies its own OpenSSL context, the
+     * plug-in ignores configuration properties related to certificates,
+     * keys, and passwords.
+     *
+     * Note that the plug-in assumes ownership of the given context.
+     *
+     * @param ctx The OpenSSL context.
+     */
+    virtual void setContext(SSL_CTX* ctx) = 0;
+
+    /**
+     * Obtains the SSL context. Use caution when modifying this value.
+     * Changes made to this value have no effect on existing connections.
+     * @return The OpenSSL context.
+     */
+    virtual SSL_CTX* getContext() = 0;
 };
 ICE_DEFINE_PTR(PluginPtr, Plugin);
 

data/ext/ice/cpp/include/IceSSL/Plugin.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,22 +36,31 @@
 namespace IceSSL
 {
 
-//
-// This exception is thrown if the certificate cannot be read.
-//
+/**
+ * Thrown if the certificate cannot be read.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API CertificateReadException : public IceUtil::ExceptionHelper<CertificateReadException>
 {
 public:
 
     CertificateReadException(const char*, int, const std::string&);
+
 #ifndef ICE_CPP11_COMPILER
     virtual ~CertificateReadException() throw();
 #endif
+
     virtual std::string ice_id() const;
+
 #ifndef ICE_CPP11_MAPPING
+    /**
+     * Creates a shallow copy of this exception.
+     * @return The new exception instance.
+     */
     virtual CertificateReadException* ice_clone() const;
 #endif
 
+    /** The reason for the exception. */
     std::string reason;
 
 private:
@@ -59,22 +68,31 @@ private:
     static const char* _name;
 };
 
-//
-// This exception is thrown if the certificate cannot be encoded.
-//
+/**
+ * Thrown if the certificate cannot be encoded.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API CertificateEncodingException : public IceUtil::ExceptionHelper<CertificateEncodingException>
 {
 public:
 
     CertificateEncodingException(const char*, int, const std::string&);
+
 #ifndef ICE_CPP11_COMPILER
     virtual ~CertificateEncodingException() throw();
 #endif
+
     virtual std::string ice_id() const;
+
 #ifndef ICE_CPP11_MAPPING
+    /**
+     * Creates a shallow copy of this exception.
+     * @return The new exception instance.
+     */
     virtual CertificateEncodingException* ice_clone() const;
 #endif
 
+    /** The reason for the exception. */
     std::string reason;
 
 private:
@@ -82,22 +100,31 @@ private:
     static const char* _name;
 };
 
-//
-// This exception is thrown if a distinguished name cannot be parsed.
-//
+/**
+ * This exception is thrown if a distinguished name cannot be parsed.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API ParseException : public IceUtil::ExceptionHelper<ParseException>
 {
 public:
 
     ParseException(const char*, int, const std::string&);
+
 #ifndef ICE_CPP11_COMPILER
     virtual ~ParseException() throw();
 #endif
+
     virtual std::string ice_id() const;
+
 #ifndef ICE_CPP11_MAPPING
+    /**
+     * Creates a shallow copy of this exception.
+     * @return The new exception instance.
+     */
     virtual ParseException* ice_clone() const;
 #endif
 
+    /** The reason for the exception. */
     std::string reason;
 
 private:
@@ -105,61 +132,76 @@ private:
     static const char* _name;
 };
 
-//
-// This class represents a DistinguishedName, similar to the Java
-// type X500Principal and the .NET type X500DistinguishedName.
-//
-// For comparison purposes, the value of a relative distinguished
-// name (RDN) component is always unescaped before matching,
-// therefore "ZeroC, Inc." will match ZeroC\, Inc.
-//
-// toString() always returns exactly the same information as was
-// provided in the constructor (i.e., "ZeroC, Inc." will not turn
-// into ZeroC\, Inc.).
-//
+/**
+ * This class represents a DistinguishedName, similar to the Java
+ * type X500Principal and the .NET type X500DistinguishedName.
+ *
+ * For comparison purposes, the value of a relative distinguished
+ * name (RDN) component is always unescaped before matching,
+ * therefore "ZeroC, Inc." will match ZeroC\, Inc.
+ *
+ * toString() always returns exactly the same information as was
+ * provided in the constructor (i.e., "ZeroC, Inc." will not turn
+ * into ZeroC\, Inc.).
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API DistinguishedName
 {
 public:
 
-    //
-    // Create a DistinguishedName from a string encoded using
-    // the rules in RFC2253.
-    //
-    // Throws ParseException if parsing fails.
-    //
-    explicit DistinguishedName(const std::string&);
-
-    //
-    // Create a DistinguishedName from a list of RDN pairs,
-    // where each pair consists of the RDN's type and value.
-    // For example, the RDN "O=ZeroC" is represented by the
-    // pair ("O", "ZeroC").
-    //
+    /**
+     * Creates a DistinguishedName from a string encoded using the rules in RFC2253.
+     * @param name The encoded distinguished name.
+     * @throws ParseException if parsing fails.
+     */
+    explicit DistinguishedName(const std::string& name);
+
+    /**
+     * Creates a DistinguishedName from a list of RDN pairs,
+     * where each pair consists of the RDN's type and value.
+     * For example, the RDN "O=ZeroC" is represented by the
+     * pair ("O", "ZeroC").
+     * @throws ParseException if parsing fails.
+     */
     explicit DistinguishedName(const std::list<std::pair<std::string, std::string> >&);
 
-    //
-    // This is an exact match. The order of the RDN components is
-    // important.
-    //
+    /**
+     * Performs an exact match. The order of the RDN components is important.
+     */
     friend ICESSL_API bool operator==(const DistinguishedName&, const DistinguishedName&);
+
+    /**
+     * Performs an exact match. The order of the RDN components is important.
+     */
     friend ICESSL_API bool operator<(const DistinguishedName&, const DistinguishedName&);
 
-    //
-    // Perform a partial match with another DistinguishedName. The function
-    // returns true if all of the RDNs in the argument are present in this
-    // DistinguishedName and they have the same values.
-    //
-    bool match(const DistinguishedName&) const;
-    bool match(const std::string&) const;
-
-    //
-    // Encode the DN in RFC2253 format.
-    //
+    /**
+     * Performs a partial match with another DistinguishedName.
+     * @param dn The name to be matched.
+     * @return True if all of the RDNs in the argument are present in this
+     * DistinguishedName and they have the same values.
+     */
+    bool match(const DistinguishedName& dn) const;
+
+    /**
+     * Performs a partial match with another DistinguishedName.
+     * @param dn The name to be matched.
+     * @return True if all of the RDNs in the argument are present in this
+     * DistinguishedName and they have the same values.
+     */
+    bool match(const std::string& dn) const;
+
+    /**
+     * Encodes the DN in RFC2253 format.
+     * @return An encoded string.
+     */
     operator std::string() const;
 
 protected:
 
+    /// \cond INTERNAL
     void unescape();
+    /// \endcond
 
 private:
 
@@ -167,33 +209,46 @@ private:
     std::list<std::pair<std::string, std::string> > _unescaped;
 };
 
+/**
+ * Performs an exact match. The order of the RDN components is important.
+ */
 inline bool
 operator>(const DistinguishedName& lhs, const DistinguishedName& rhs)
 {
     return rhs < lhs;
 }
 
+/**
+ * Performs an exact match. The order of the RDN components is important.
+ */
 inline bool
 operator<=(const DistinguishedName& lhs, const DistinguishedName& rhs)
 {
     return !(lhs > rhs);
 }
 
+/**
+ * Performs an exact match. The order of the RDN components is important.
+ */
 inline bool
 operator>=(const DistinguishedName& lhs, const DistinguishedName& rhs)
 {
     return !(lhs < rhs);
 }
 
+/**
+ * Performs an exact match. The order of the RDN components is important.
+ */
 inline bool
 operator!=(const DistinguishedName& lhs, const DistinguishedName& rhs)
 {
     return !(lhs == rhs);
 }
 
-//
-// This class represents an X509 Certificate extension.
-//
+/**
+ * Represents an X509 Certificate extension.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API X509Extension
 #ifndef ICE_CPP11_MAPPING
     : public virtual IceUtil::Shared
@@ -201,267 +256,317 @@ class ICESSL_API X509Extension
 {
 public:
 
+    /**
+     * Determines whether the information in this extension is important.
+     * @return True if if information is important, false otherwise.
+     */
     virtual bool isCritical() const = 0;
+
+    /**
+     * Obtains the object ID of this extension.
+     * @return The object ID.
+     */
     virtual std::string getOID() const = 0;
+
+    /**
+     * Obtains the data associated with this extension.
+     * @return The extension data.
+     */
     virtual std::vector<Ice::Byte> getData() const = 0;
 };
 ICE_DEFINE_PTR(X509ExtensionPtr, X509Extension);
 
-//
-// This convenience class is a wrapper around a native certificate.
-// The interface is inspired by java.security.cert.X509Certificate.
-//
-
 class Certificate;
 ICE_DEFINE_PTR(CertificatePtr, Certificate);
 
+/**
+ * This convenience class is a wrapper around a native certificate.
+ * The interface is inspired by java.security.cert.X509Certificate.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API Certificate :
 #ifdef ICE_CPP11_MAPPING
-        public std::enable_shared_from_this<Certificate>
+    public std::enable_shared_from_this<Certificate>
 #else
-        public virtual IceUtil::Shared
+    public virtual IceUtil::Shared
 #endif
 {
 public:
 
-    //
-    // Compare the certificates for equality using the
-    // native certificate comparison method.
-    //
+    /**
+     * Compares the certificates for equality using the native certificate comparison method.
+     */
     virtual bool operator==(const Certificate&) const = 0;
+
+    /**
+     * Compares the certificates for equality using the native certificate comparison method.
+     */
     virtual bool operator!=(const Certificate&) const = 0;
 
-    //
-    // Authority key identifier
-    //
+    /**
+     * Obtains the authority key identifier.
+     * @return The identifier.
+     */
     virtual std::vector<Ice::Byte> getAuthorityKeyIdentifier() const = 0;
 
-    //
-    // Subject key identifier
-    //
+    /**
+     * Obtains the subject key identifier.
+     * @return The identifier.
+     */
     virtual std::vector<Ice::Byte> getSubjectKeyIdentifier() const = 0;
 
-    //
-    // Verify that this certificate was signed by the given certificate
-    // public key. Returns true if signed, false otherwise.
-    //
-    virtual bool verify(const CertificatePtr&) const = 0;
-
-    //
-    // Return a string encoding of the certificate in PEM format.
-    // Raises CertificateEncodingException if an error occurs.
-    //
+    /**
+     * Verifies that this certificate was signed by the given certificate
+     * public key.
+     * @param cert A certificate containing the public key.
+     * @return True if signed, false otherwise.
+     */
+    virtual bool verify(const CertificatePtr& cert) const = 0;
+
+    /**
+     * Obtains a string encoding of the certificate in PEM format.
+     * @return The encoded certificate.
+     * @throws CertificateEncodingException if an error occurs.
+     */
     virtual std::string encode() const = 0;
 
-    //
-    // Checks that the certificate is currently valid, that is, the current
-    // date falls between the validity period given in the certificate.
-    //
+    /**
+     * Checks that the certificate is currently valid, that is, the current
+     * date falls between the validity period given in the certificate.
+     * @return True if the certificate is valid, false otherwise.
+     */
     virtual bool checkValidity() const = 0;
 
-    //
-    // Checks that the certificate is valid at the given time.
-    //
+    /**
+     * Checks that the certificate is valid at the given time.
+     * @param t The target time.
+     * @return True if the certificate is valid, false otherwise.
+     */
 #ifdef ICE_CPP11_MAPPING
-    virtual bool checkValidity(const std::chrono::system_clock::time_point&) const = 0;
+    virtual bool checkValidity(const std::chrono::system_clock::time_point& t) const = 0;
 #else
-    virtual bool checkValidity(const IceUtil::Time&) const = 0;
+    virtual bool checkValidity(const IceUtil::Time& t) const = 0;
 #endif
 
-    //
-    // Get the not-after validity time.
-    //
+    /**
+     * Obtains the not-after validity time.
+     * @return The time after which this certificate is invalid.
+     */
 #ifdef ICE_CPP11_MAPPING
     virtual std::chrono::system_clock::time_point getNotAfter() const = 0;
 #else
     virtual IceUtil::Time getNotAfter() const = 0;
 #endif
 
-    //
-    // Get the not-before validity time.
-    //
+    /**
+     * Obtains the not-before validity time.
+     * @return The time at which this certificate is valid.
+     */
 #ifdef ICE_CPP11_MAPPING
     virtual std::chrono::system_clock::time_point getNotBefore() const = 0;
 #else
     virtual IceUtil::Time getNotBefore() const = 0;
 #endif
 
-    //
-    // Get the serial number. This is an arbitrarily large number.
-    //
+    /**
+     * Obtains the serial number. This is an arbitrarily large number.
+     * @return The certificate's serial number.
+     */
     virtual std::string getSerialNumber() const = 0;
 
-    //
-    // Get the issuer's distinguished name (DN).
-    //
+    /**
+     * Obtains the issuer's distinguished name (DN).
+     * @return The distinguished name.
+     */
     virtual DistinguishedName getIssuerDN() const = 0;
 
-    //
-    // Get the values in the issuer's alternative names extension.
-    //
-    // The returned list contains a pair of int, string.
-    //
-    // otherName                       [0]     OtherName
-    // rfc822Name                      [1]     IA5String
-    // dNSName                         [2]     IA5String
-    // x400Address                     [3]     ORAddress
-    // directoryName                   [4]     Name
-    // ediPartyName                    [5]     EDIPartyName
-    // uniformResourceIdentifier       [6]     IA5String
-    // iPAddress                       [7]     OCTET STRING
-    // registeredID                    [8]     OBJECT IDENTIFIER
-    //
-    // rfc822Name, dNSName, directoryName and
-    // uniformResourceIdentifier data is returned as a string.
-    //
-    // iPAddress is returned in dotted quad notation. IPv6 is not
-    // currently supported.
-    //
-    // All distinguished names are encoded in RFC2253 format.
-    //
-    // The remainder of the data will result in an empty string. Use the raw
-    // X509* certificate to obtain these values.
-    //
+    /**
+     * Obtains the values in the issuer's alternative names extension.
+     *
+     * The returned list contains a pair of int, string.
+     *
+     * otherName                       [0]     OtherName
+     * rfc822Name                      [1]     IA5String
+     * dNSName                         [2]     IA5String
+     * x400Address                     [3]     ORAddress
+     * directoryName                   [4]     Name
+     * ediPartyName                    [5]     EDIPartyName
+     * uniformResourceIdentifier       [6]     IA5String
+     * iPAddress                       [7]     OCTET STRING
+     * registeredID                    [8]     OBJECT IDENTIFIER
+     *
+     * rfc822Name, dNSName, directoryName and
+     * uniformResourceIdentifier data is returned as a string.
+     *
+     * iPAddress is returned in dotted quad notation. IPv6 is not
+     * currently supported.
+     *
+     * All distinguished names are encoded in RFC2253 format.
+     *
+     * The remainder of the data will result in an empty string. Use the raw
+     * X509* certificate to obtain these values.
+     *
+     * @return The issuer's alternative names.
+     */
     virtual std::vector<std::pair<int, std::string> > getIssuerAlternativeNames() const = 0;
 
-    //
-    // Get the subject's distinguished name (DN).
-    //
+    /**
+     * Obtains the subject's distinguished name (DN).
+     * @return The distinguished name.
+     */
     virtual DistinguishedName getSubjectDN() const = 0;
 
-    //
-    // See the comment for getIssuerAlternativeNames.
-    //
+    /**
+     * See the comment for Plugin::getIssuerAlternativeNames.
+     * @return The subject's alternative names.
+     */
     virtual std::vector<std::pair<int, std::string> > getSubjectAlternativeNames() const = 0;
 
-    //
-    // Retrieve the certificate version number.
-    //
+    /**
+     * Obtains the certificate version number.
+     * @return The version number.
+     */
     virtual int getVersion() const = 0;
 
-    //
-    // Stringify the certificate. This is a human readable version of
-    // the certificate, not a DER or PEM encoding.
-    //
+    /**
+     * Stringifies the certificate. This is a human readable version of
+     * the certificate, not a DER or PEM encoding.
+     * @return A string version of the certificate.
+     */
     virtual std::string toString() const = 0;
 
-    //
-    // Return a list with the X509v3 extensions contained in the
-    // certificate.
-    //
+    /**
+     * Obtains a list of the X509v3 extensions contained in the certificate.
+     * @return The extensions.
+     */
     virtual std::vector<X509ExtensionPtr> getX509Extensions() const = 0;
 
-    //
-    // Return the extension with the given OID or null if the certificate
-    // does not contain a extension with the given OID.
-    //
-    virtual X509ExtensionPtr getX509Extension(const std::string&) const = 0;
-
-    //
-    // Load the certificate from a file. The certificate must use the
-    // PEM encoding format. Raises CertificateReadException if the
-    // file cannot be read.
-    //
-    static CertificatePtr load(const std::string&);
-
-    //
-    // Decode a certificate from a string that uses the PEM encoding
-    // format. Raises CertificateEncodingException if an error
-    // occurs.
-    //
-    static CertificatePtr decode(const std::string&);
+    /**
+     * Obtains the extension with the given OID.
+     * @return The extension, or null if the certificate
+     * does not contain a extension with the given OID.
+     */
+    virtual X509ExtensionPtr getX509Extension(const std::string& oid) const = 0;
+
+    /**
+     * Loads the certificate from a file. The certificate must use the
+     * PEM encoding format.
+     * @param file The certificate file.
+     * @return The new certificate instance.
+     * @throws CertificateReadException if the file cannot be read.
+     */
+    static CertificatePtr load(const std::string& file);
+
+    /**
+     * Decodes a certificate from a string that uses the PEM encoding format.
+     * @param str A string containing the encoded certificate.
+     * @throws CertificateEncodingException if an error occurs.
+     */
+    static CertificatePtr decode(const std::string& str);
 };
 
 #ifndef ICE_CPP11_MAPPING // C++98 mapping
-//
-// An application can customize the certificate verification process
-// by implementing the CertificateVerifier interface.
-//
 
+/**
+ * An application can customize the certificate verification process
+ * by implementing the CertificateVerifier interface.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API CertificateVerifier : public IceUtil::Shared
 {
 public:
 
     virtual ~CertificateVerifier();
 
-    //
-    // Return false if the connection should be rejected, or true to
-    // allow it.
-    //
-    virtual bool verify(const ConnectionInfoPtr&) = 0;
+    /**
+     * Determines whether to accept a certificate.
+     * @param info Information about the connection.
+     * @return False if the connection should be rejected, or true to allow it.
+     */
+    virtual bool verify(const ConnectionInfoPtr& info) = 0;
 };
 typedef IceUtil::Handle<CertificateVerifier> CertificateVerifierPtr;
 
-//
-// In order to read an encrypted file, such as one containing a
-// private key, OpenSSL requests a password from IceSSL. The password
-// can be defined using an IceSSL configuration property, but a
-// plain-text password is a security risk. If a password is not
-// supplied via configuration, IceSSL allows OpenSSL to prompt the
-// user interactively.  This may not be desirable (or even possible),
-// so the application can supply an implementation of PasswordPrompt
-// to take responsibility for obtaining the password.
-//
-// Note that the password is needed during plug-in initialization, so
-// in general you will need to delay initialization (by defining
-// IceSSL.DelayInit=1), configure the PasswordPrompt, then manually
-// initialize the plug-in.
-//
+/**
+ * In order to read an encrypted file, such as one containing a
+ * private key, OpenSSL requests a password from IceSSL. The password
+ * can be defined using an IceSSL configuration property, but a
+ * plain-text password is a security risk. If a password is not
+ * supplied via configuration, IceSSL allows OpenSSL to prompt the
+ * user interactively. This may not be desirable (or even possible),
+ * so the application can supply an implementation of PasswordPrompt
+ * to take responsibility for obtaining the password.
+ *
+ * Note that the password is needed during plug-in initialization, so
+ * in general you will need to delay initialization (by defining
+ * IceSSL.DelayInit=1), configure the PasswordPrompt, then manually
+ * initialize the plug-in.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API PasswordPrompt : public IceUtil::Shared
 {
 public:
 
     virtual ~PasswordPrompt();
 
-    //
-    // The getPassword method may be invoked repeatedly, such as when
-    // several encrypted files are opened, or when multiple password
-    // attempts are allowed.
-    //
+    /**
+     * Obtains the password. This method may be invoked repeatedly, such as when
+     * several encrypted files are opened, or when multiple password
+     * attempts are allowed.
+     * @return The clear-text password.
+     */
     virtual std::string getPassword() = 0;
 };
 typedef IceUtil::Handle<PasswordPrompt> PasswordPromptPtr;
 #endif
 
+/**
+ * Represents the IceSSL plug-in object.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_API Plugin : public Ice::Plugin
 {
 public:
 
     virtual ~Plugin();
 
-    //
-    // Establish the certificate verifier object. This should be done
-    // before any connections are established.
-    //
+    /**
+     * Establish the certificate verifier object. This should be done
+     * before any connections are established.
+     * @param v The verifier.
+     */
 #ifdef ICE_CPP11_MAPPING
-    virtual void setCertificateVerifier(std::function<bool(const std::shared_ptr<ConnectionInfo>&)>) = 0;
+    virtual void setCertificateVerifier(std::function<bool(const std::shared_ptr<ConnectionInfo>&)> v) = 0;
 #else
-    virtual void setCertificateVerifier(const CertificateVerifierPtr&) = 0;
+    virtual void setCertificateVerifier(const CertificateVerifierPtr& v) = 0;
 #endif
 
-    //
-    // Establish the password prompt object. This must be done before
-    // the plug-in is initialized.
-    //
+    /**
+     * Establish the password prompt object. This must be done before
+     * the plug-in is initialized.
+     * @param p The password prompt.
+     */
 #ifdef ICE_CPP11_MAPPING
-    virtual void setPasswordPrompt(std::function<std::string()>) = 0;
+    virtual void setPasswordPrompt(std::function<std::string()> p) = 0;
 #else
-    virtual void setPasswordPrompt(const PasswordPromptPtr&) = 0;
+    virtual void setPasswordPrompt(const PasswordPromptPtr& p) = 0;
 #endif
 
-    //
-    // Load the certificate from a file. The certificate must use the
-    // PEM encoding format. Raises CertificateReadException if the
-    // file cannot be read.
-    //
-    virtual CertificatePtr load(const std::string&) const = 0;
-
-    //
-    // Decode a certificate from a string that uses the PEM encoding
-    // format. Raises CertificateEncodingException if an error
-    // occurs.
-    //
-    virtual CertificatePtr decode(const std::string&) const = 0;
+    /**
+     * Load the certificate from a file. The certificate must use the
+     * PEM encoding format.
+     * @param file The certificate file.
+     * @throws CertificateReadException if the file cannot be read.
+     */
+    virtual CertificatePtr load(const std::string& file) const = 0;
+
+    /**
+     * Decode a certificate from a string that uses the PEM encoding
+     * format.
+     * @param str A string containing the encoded certificate.
+     * @throws CertificateEncodingException if an error occurs.
+     */
+    virtual CertificatePtr decode(const std::string& str) const = 0;
 };
 ICE_DEFINE_PTR(PluginPtr, Plugin);