uhd: Improve documentation for the UHD exception types

1 files changed, 51 insertions, 0 deletions

diff --git a/host/include/uhd/exception.hpp b/host/include/uhd/exception.hpp
index 1d8f0bba0..727c09697 100644
--- a/host/include/uhd/exception.hpp
+++ b/host/include/uhd/exception.hpp
@@ -32,6 +32,8 @@
  */
 namespace uhd{
 
+    /*! Base class of all UHD-specific exceptions.
+     */
     struct UHD_API exception : std::runtime_error{
         exception(const std::string &what);
         virtual unsigned code(void) const = 0;
@@ -39,6 +41,10 @@ namespace uhd{
         virtual void dynamic_throw(void) const = 0;
     };
 
+    /*! Raised when an assert statement fails.
+     *
+     * This includes our own assertion macros, such as UHD_ASSERT_THROW().
+     */
     struct UHD_API assertion_error : exception{
         assertion_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -46,6 +52,9 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! The base class for exceptions that are raised when a key or index is
+     * invalid.
+     */
     struct UHD_API lookup_error : exception{
         lookup_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -53,6 +62,8 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when a sequence index is out of range.
+     */
     struct UHD_API index_error : lookup_error{
         index_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -60,6 +71,11 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when a dictionary-like object is trying to be indexed by an
+     *  invalid key.
+     *
+     * This includes the property tree.
+     */
     struct UHD_API key_error : lookup_error{
         key_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -67,6 +83,12 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when an operation or function is executed with a value of
+     *  incorrect type.
+     *
+     * This might occur when values are being passed around as strings, but the
+     * underlying code will need convert to a native type.
+     */
     struct UHD_API type_error : exception{
         type_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -74,6 +96,10 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when an operation or function receives an argument that has the
+     * right type but an inappropriate or invalid value, and no other exception
+     * is more specific.
+     */
     struct UHD_API value_error : exception{
         value_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -81,6 +107,11 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when a value is inappropriate because it can't be narrowed as
+     * required.
+     *
+     * Mostly raised by uhd::narrow()
+     */
     struct UHD_API narrowing_error : value_error{
         narrowing_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -88,6 +119,9 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when an error is detected that doesn't fall into any of the
+     * categories.
+     */
     struct UHD_API runtime_error : exception{
         runtime_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -95,6 +129,8 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when an error occurs during a USB transaction.
+     */
     struct UHD_API usb_error : runtime_error{
         int _code;
         usb_error(int code, const std::string &what);
@@ -103,6 +139,9 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when a function is stubbed out but doesn't actually do anything
+     * useful.
+     */
     struct UHD_API not_implemented_error : runtime_error{
         not_implemented_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -110,6 +149,8 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Base class for errors that occur outside of UHD.
+     */
     struct UHD_API environment_error : exception{
         environment_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -117,6 +158,8 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when an I/O operation fails for an I/O-related reason.
+     */
     struct UHD_API io_error : environment_error{
         io_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -124,6 +167,8 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when a function returns a system-related error.
+     */
     struct UHD_API os_error : environment_error{
         os_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -131,6 +176,8 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! \deprecated
+     */
     struct UHD_API system_error : exception{
         system_error(const std::string &what);
         virtual unsigned code(void) const;
@@ -138,6 +185,10 @@ namespace uhd{
         virtual void dynamic_throw(void) const;
     };
 
+    /*! Raised when a parser encounters a syntax error.
+     *
+     * Within UHD, this is limited to Noc-Script execution.
+     */
     struct UHD_API syntax_error : exception{
         syntax_error(const std::string &what);
         virtual unsigned code(void) const;