Doxygen comments in IceUtil/Exception.h + related fixes

Fixes #234

3 files changed, 156 insertions, 47 deletions

diff --git a/cpp/include/Ice/ExceptionHelpers.h b/cpp/include/Ice/ExceptionHelpers.h
index c0a2c05086f..286141bdd6b 100644
--- a/cpp/include/Ice/ExceptionHelpers.h
+++ b/cpp/include/Ice/ExceptionHelpers.h
@@ -21,7 +21,7 @@ namespace Ice
 class LocalException;
 
 /**
- * Helper template for local exceptions.
+ * Helper template for the implementation of Ice::LocalException. It implements ice_id.
  * \headerfile Ice/Ice.h
  */
 template<typename T, typename B> class LocalExceptionHelper : public IceUtil::ExceptionHelper<T, B>
@@ -30,10 +30,6 @@ 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();
@@ -41,7 +37,7 @@ public:
 };
 
 /**
- * Helper template for user exceptions.
+ * Helper template for the implementation of Ice::UserException. It implements ice_id.
  * \headerfile Ice/Ice.h
  */
 template<typename T, typename B> class UserExceptionHelper : public IceUtil::ExceptionHelper<T, B>
@@ -50,10 +46,6 @@ 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();
diff --git a/cpp/include/IceUtil/CtrlCHandler.h b/cpp/include/IceUtil/CtrlCHandler.h
index cc32c6cad6e..601bc090b3c 100644
--- a/cpp/include/IceUtil/CtrlCHandler.h
+++ b/cpp/include/IceUtil/CtrlCHandler.h
@@ -18,7 +18,7 @@ namespace IceUtil
 
 /**
  * Invoked when a signal occurs. The callback must not raise exceptions.
- * On Unix/POSIX, the callback is NOT a signal handler and can call
+ * On Linux and macOS, the callback is NOT a signal handler and can call
  * functions that are not async-signal safe.
  * @param sig The signal number that occurred.
  */
@@ -29,43 +29,36 @@ typedef void (*CtrlCHandlerCallback)(int sig);
 #endif
 
 /**
- * Provides a portable way to handle CTRL+C and CTRL+C like signals.
- * On Unix/POSIX, the CtrlCHandler handles SIGHUP, SIGINT and SIGTERM.
+ * Provides a portable way to handle Ctrl-C and Ctrl-C like signals.
+ * On Linux and macOS, the CtrlCHandler handles SIGHUP, SIGINT and SIGTERM.
  * On Windows, it is essentially a wrapper for SetConsoleCtrlHandler().
  *
- * In a process, only one CtrlCHandler can exist at a given time:
- * the CtrlCHandler constructor raises CtrlCHandlerException if
- * you attempt to create a second CtrlCHandler.
- * On Unix/POSIX, it is essential to create the CtrlCHandler before
- * creating any thread, as the CtrlCHandler constructor masks (blocks)
- * SIGHUP, SIGINT and SIGTERM; by default, threads created later will
- * inherit this signal mask.
- *
- * When a CTRL+C or CTRL+C like signal is sent to the process, the
- * user-registered callback is called in a separate thread; it is
- * given the signal number. The callback must not raise exceptions.
- * On Unix/POSIX, the callback is NOT a signal handler and can call
- * functions that are not async-signal safe.
- *
- * The CtrCHandler destructor "unregisters" the callback. However
- * on Unix/POSIX it does not restore the old signal mask in any
- * thread, so SIGHUP, SIGINT and SIGTERM remain blocked.
- *
- * \headerfile IceUtil/CtrlCHandler.h
+ * \headerfile Ice/Ice.h
  */
-//
-// TODO: Maybe the behavior on Windows should be the same? Now we
-// just restore the default behavior (TerminateProcess).
-//
 class ICE_API CtrlCHandler
 {
 public:
 
-    /**
-     * Initializes the relevant signals.
-     * @param cb The signal callback.
+     /**
+     * Registers a callback function that handles Ctrl-C like signals.
+     * On Linux and macOS, this constructor masks the SIGHUP, SIGINT and SIGTERM
+     * signals and then creates a thread that waits for these signals using sigwait.
+     * On Windows, this constructor calls SetConsoleCtrlCHandler to register a handler
+     * routine that calls the supplied callback function.
+     * Only a single CtrlCHandler object can exist in a process at a give time.
+     * @param cb The callback function to invoke when a signal is received.
      */
     explicit CtrlCHandler(CtrlCHandlerCallback cb = ICE_NULLPTR);
+
+     /**
+     * Unregisters the callback function.
+     * On Linux and macOS, this destructor joins and terminates the thread created
+     * by the constructor but does not "unmask" SIGHUP, SIGINT and SIGTERM. As a result,
+     * these signals are ignored after this destructor completes.
+     * On Windows, this destructor unregisters the SetConsoleCtrlHandler handler
+     * routine, and as a result a Ctrl-C or similar signal will terminate the application
+     * after this destructor completes.
+     */
     ~CtrlCHandler();
 
     /**
@@ -77,15 +70,15 @@ public:
 
     /**
      * Obtains the signal callback.
-     * @return The callback, or nil if no callback is currently set.
+     * @return The callback.
      */
     CtrlCHandlerCallback getCallback() const;
 };
 
 /**
- * Raised by CtrlCHandler.
+ * Raised by the CtrlCHandler constructor if another CtrlCHandler already exists.
  *
- * \headerfile IceUtil/CtrlCHandler.h
+ * \headerfile Ice/Ice.h
  */
 class ICE_API CtrlCHandlerException : public ExceptionHelper<CtrlCHandlerException>
 {
diff --git a/cpp/include/IceUtil/Exception.h b/cpp/include/IceUtil/Exception.h
index fb3ee49cd9d..710157556d8 100644
--- a/cpp/include/IceUtil/Exception.h
+++ b/cpp/include/IceUtil/Exception.h
@@ -18,35 +18,97 @@
 namespace IceUtil
 {
 
+/**
+ * Abstract base class for all Ice exceptions. Use the Ice::Exception alias instead
+ * of IceUtil::Exception.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Exception : public std::exception
 {
 public:
 
+    /**
+     * Constructs the exception. Equivalent to Exception(nullptr, 0).
+     */
     Exception();
-    Exception(const char*, int);
+
+    /**
+     * Constructs the exception.
+     * @param file The file where this exception is constructed.
+     * @param line The line where this exception is constructed.
+     */
+    Exception(const char* file, int line);
+
 #ifndef ICE_CPP11_COMPILER
     virtual ~Exception() throw() = 0;
 #endif
+
+    /**
+     * Returns the type ID of this exception. This corresponds to the Slice
+     * type ID for Slice-defined exceptions, and to a similar fully scoped name
+     * for other exceptions. For example "::IceUtil::SyscallException".
+     * @return The type ID of this exception
+     */
     virtual std::string ice_id() const = 0;
-    virtual void ice_print(std::ostream&) const;
+
+    /**
+     * Outputs a description of this exception to a stream.
+     * @param os The output stream.
+     */
+    virtual void ice_print(std::ostream& os) const;
+
+    /**
+     * Returns a description of this exception.
+     * @return The description.
+     */
     virtual const char* what() const ICE_NOEXCEPT;
 #ifdef ICE_CPP11_MAPPING
+
+    /**
+     * Returns a shallow polymorphic copy of this exception.
+     * @return A unique_ptr to the new shallow copy.
+     */
     std::unique_ptr<Exception> ice_clone() const;
 #else
+    /**
+     * Returns a shallow polymorphic copy of this exception.
+     * @return A pointer to the new shallow copy. The caller owns the returned object.
+     */
     virtual Exception* ice_clone() const = 0;
+
     ICE_DEPRECATED_API("ice_name() is deprecated, use ice_id() instead.")
     std::string ice_name() const;
 #endif
+
+    /**
+     * Throws this exception.
+     */
     virtual void ice_throw() const = 0;
 
+    /**
+     * Returns the name of the file where this exception was constructed.
+     * @return The file name.
+     */
     const char* ice_file() const;
+
+    /**
+     * Returns the line number where this exception was constructed.
+     * @return The line number.
+     */
     int ice_line() const;
+
+    /**
+     * Returns the stack trace at the point this exception was constructed
+     * @return The stack trace as a string.
+     */
     std::string ice_stackTrace() const;
 
 protected:
 
 #ifdef ICE_CPP11_MAPPING
+    /// \cond INTERNAL
     virtual Exception* ice_cloneImpl() const = 0;
+    /// \endcond
 #endif
 
 private:
@@ -61,6 +123,11 @@ ICE_API std::ostream& operator<<(std::ostream&, const Exception&);
 
 #ifdef ICE_CPP11_MAPPING
 
+/**
+ * Helper template for the implementation of Ice::Exception.
+ * It implements ice_clone and ice_throw.
+ * \headerfile Ice/Ice.h
+ */
 template<typename E, typename B = Exception>
 class ExceptionHelper : public B
 {
@@ -80,14 +147,20 @@ public:
 
 protected:
 
+    /// \cond INTERNAL
     virtual Exception* ice_cloneImpl() const override
     {
         return new E(static_cast<const E&>(*this));
     }
+    /// \endcond
 };
 
 #else // C++98 mapping
 
+/**
+ * Helper template for the implementation of Ice::Exception. It implements ice_throw.
+ * \headerfile Ice/Ice.h
+ */
 template<typename E>
 class ExceptionHelper : public Exception
 {
@@ -109,6 +182,11 @@ public:
 
 #endif
 
+/**
+ * This exception indicates an attempt to dereference a null IceUtil::Handle or
+ * IceInternal::Handle.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API NullHandleException : public ExceptionHelper<NullHandleException>
 {
 public:
@@ -121,6 +199,12 @@ public:
 #endif
 };
 
+/**
+ * This exception indicates that a function was called with an illegal parameter
+ * value. It is used only by the Slice to C++98 mapping; std::invalid_argument is
+ * used by the Slice to C++11 mapping.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API IllegalArgumentException : public ExceptionHelper<IllegalArgumentException>
 {
 public:
@@ -139,6 +223,10 @@ public:
     virtual IllegalArgumentException* ice_clone() const;
 #endif
 
+    /**
+     * Provides the reason this exception was thrown.
+     * @return The reason.
+     */
     std::string reason() const;
 
 private:
@@ -146,9 +234,10 @@ private:
     const std::string _reason;
 };
 
-//
-// IllegalConversionException is raised to report a string conversion error
-//
+/**
+ * This exception indicates the failure of a string conversion.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API IllegalConversionException : public ExceptionHelper<IllegalConversionException>
 {
 public:
@@ -167,6 +256,10 @@ public:
     virtual IllegalConversionException* ice_clone() const;
 #endif
 
+    /**
+     * Provides the reason this exception was thrown.
+     * @return The reason.
+     */
     std::string reason() const;
 
 private:
@@ -174,6 +267,10 @@ private:
     const std::string _reason;
 };
 
+/**
+ * This exception indicates the failure of a system call.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API SyscallException : public ExceptionHelper<SyscallException>
 {
 public:
@@ -191,6 +288,10 @@ public:
     virtual SyscallException* ice_clone() const;
 #endif
 
+    /**
+     * Provides the error number returned by the system call.
+     * @return The error number.
+     */
     int error() const;
 
 private:
@@ -205,6 +306,11 @@ using SyscallExceptionHelper = ExceptionHelper<E, SyscallException>;
 
 #else // C++98 mapping
 
+/**
+* Helper template for the implementation of SyscallException. It implements
+* ice_throw.
+* \headerfile Ice/Ice.h
+*/
 template<typename E>
 class SyscallExceptionHelper : public SyscallException
 {
@@ -223,6 +329,10 @@ public:
 
 #endif
 
+/**
+ * This exception indicates the failure to lock a file.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API FileLockException : public ExceptionHelper<FileLockException>
 {
 public:
@@ -240,7 +350,16 @@ public:
     virtual FileLockException* ice_clone() const;
 #endif
 
+    /**
+     * Returns the path to the file.
+     * @return The file path.
+     */
     std::string path() const;
+
+    /**
+     * Returns the error number for the failed locking attempt.
+     * @return The error number.
+     */
     int error() const;
 
 private:
@@ -249,6 +368,11 @@ private:
     std::string _path;
 };
 
+/**
+ * This exception indicates an IceUtil::Optional is not set.
+ * Used only by the Slice to C++98 mapping.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API OptionalNotSetException : public ExceptionHelper<OptionalNotSetException>
 {
 public: