Doxygen commentary for subclasses of AudacityException

src/FileException.cpp

@@ -1,10 +1,11 @@
-//
+/*!
-//  FileException.cpp
+  @file FileException.cpp
-//  
+  @brief implements FileException
-//
+  
-//  Created by Paul Licameli on 11/22/16.
+
-//
+  Created by Paul Licameli on 11/22/16.
-//
+
+*/
 
 #include "Audacity.h"
 #include "FileException.h"

src/FileException.h

@@ -1,10 +1,11 @@
-//
+/*!
-//  FileException.h
+  @file FileException.h
-//  
+  @brief MessageBoxException for failures of file operations
-//
+  
-//  Created by Paul Licameli on 11/22/16.
+
-//
+  Created by Paul Licameli on 11/22/16.
-//
+
+*/
 
 #ifndef __AUDACITY_FILE_EXCEPTION__
 #define __AUDACITY_FILE_EXCEPTION__
@@ -12,15 +13,24 @@
 #include "AudacityException.h"
 #include <wx/filename.h> // wxFileName member variable
 
+//! Thrown for failure of file or database operations in deeply nested places
 class FileException /* not final */ : public MessageBoxException
 {
 public:
-   enum class Cause { Open, Read, Write, Rename };
+   //! Identifies file operation that failed
+   enum class Cause {
+      Open,
+      Read,
+      Write, //!< most important to detect when storage space is exhausted
+      Rename //!< involves two filenames
+   };
 
-   explicit FileException
+   explicit FileException(
-      ( Cause cause_, const wxFileName &fileName_,
+      Cause cause_, //!< What kind of file operation failed
-        const TranslatableString &caption = XO("File Error"),
+      const wxFileName &fileName_, //!< Which file suffered a failure
-        const wxFileName &renameTarget_ = {})
+      const TranslatableString &caption = XO("File Error"), //!< Shown in message box frame, not the main message
+      const wxFileName &renameTarget_ = {} //!< A second file name, only for renaming failure
+   )
    : MessageBoxException{ caption }
    , cause{ cause_ }, fileName{ fileName_ }, renameTarget{ renameTarget_ }
    {}
@@ -37,7 +47,7 @@ public:
    ~FileException() override;
 
 protected:
-   // Format a default, internationalized error message for this exception.
+   //! %Format an error message appropriate for the @ref Cause.
    TranslatableString ErrorMessage() const override;
 
 public:

src/InconsistencyException.cpp

@@ -1,10 +1,11 @@
-//
+/*!
-//  InconsistencyException.cpp
+  @file InconsistencyException.cpp
-//  
+  @brief Implements InconsistencyException
-//
+  
-//  Created by Paul Licameli on 11/27/16.
+
-//
+  Created by Paul Licameli on 11/27/16.
-//
+
+*/
 
 #include "Audacity.h"
 #include "InconsistencyException.h"

src/InconsistencyException.h

@@ -1,27 +1,36 @@
-//
+/*!
-//  InconsistencyException.h
+  @file InconsistencyException.h
-//  
+  @brief MessageBoxException for violation of preconditions or assertions
-//
+
-//  Created by Paul Licameli on 11/27/16.
+  Created by Paul Licameli on 11/27/16.
-//
+
-//  Some errors that formerly were assertion violations now throw exceptions,
+*/
-//  even in production code.  These may be violations of function preconditions
-//  or the results of logical errors internal to functions.  These conditions
-//  are supposed to be deducible statically as never happening.
-//
 
 #ifndef __AUDACITY_INCONSISTENCY_EXCEPTION__
 #define __AUDACITY_INCONSISTENCY_EXCEPTION__
 
 #include "AudacityException.h"
 
+//! Exception that should be impossible in production, thrown only from provably unreachable places
+/*!  Some errors that formerly were assertion violations now throw exceptions,
+  even in production code.  These may be violations of function preconditions
+  or the results of logical errors internal to functions.  These conditions
+  are supposed to be deducible statically as never happening.
+ 
+  The error message identifies source file and line number, possibly the function too (depending on
+  the compiler), and suggests that the user inform the development team.
+ */
 class InconsistencyException final : public MessageBoxException
 {
 public:
    InconsistencyException() {}
 
-   explicit InconsistencyException
+   //! Don't call this directly but use @ref CONSTRUCT_INCONSISTENCY_EXCEPTION or @ref THROW_INCONSISTENCY_EXCEPTION
-      ( const char *fn, const char *f, unsigned l )
+   explicit InconsistencyException(
+      const char *fn, //!< file name supplied by preprocessor
+      const char *f, //!< function name supplied by preprocessor
+      unsigned l //!< line number supplied by preprocessor
+   )
          : MessageBoxException{ XO("Internal Error") }
          , func { fn }, file { f }, line { l }
    {}
@@ -46,9 +55,6 @@ private:
    unsigned line {};
 };
 
-// This macro constructs this exception type, using C++ preprocessor to identify
-// the source code location.
-
 #ifdef __func__
 
 #define CONSTRUCT_INCONSISTENCY_EXCEPTION \
@@ -56,11 +62,18 @@ private:
 
 #else
 
+/*! @def CONSTRUCT_INCONSISTENCY_EXCEPTION
+@brief Construct InconsistencyException, using C++ preprocessor to identify the source code location
+
+For cases where the exception object is not immediately thrown */
 #define CONSTRUCT_INCONSISTENCY_EXCEPTION \
    InconsistencyException( "", __FILE__ , __LINE__ )
 
 #endif
 
+/*! @def THROW_INCONSISTENCY_EXCEPTION
+@brief Throw InconsistencyException, using C++ preprocessor to identify the source code location
+*/
 #define THROW_INCONSISTENCY_EXCEPTION throw CONSTRUCT_INCONSISTENCY_EXCEPTION
 
 #endif

src/UserException.cpp

@@ -1,10 +1,10 @@
-//
+/*!
-//  UserException.cpp
+  @file UserException.cpp
-//  
+  @brief implements UserException
-//
+
-//  Created by Paul Licameli on 11/27/16.
+  Created by Paul Licameli on 11/27/16.
-//
+
-//
+*/
 
 #include "Audacity.h"
 #include "UserException.h"

src/UserException.h

@@ -1,21 +1,18 @@
-//
+/*!
-//  UserException.h
+ @file UserException.h
-//  
+ @brief An AudacityException with no visible message
-//
+
-//  Created by Paul Licameli on 11/27/16.
+ Created by Paul Licameli on 11/27/16.
-//
+
-//  An exception to throw when the user cancels an operation, as for instance
+*/
-//  with a progress dialog.  Its delayed handler action does nothing.
-//
 
 #ifndef __AUDACITY_USER_EXCEPTION__
 #define __AUDACITY_USER_EXCEPTION__
 
 #include "AudacityException.h"
 
-// This class does not inherit from MessageBoxException, and it does nothing
+ //! Can be thrown when user cancels operations, as with a progress dialog.  Delayed handler does nothing
-// in its delayed handler.  It might be thrown after the user clicks a
+/*! This class does not inherit from MessageBoxException. */
-// cancel button, as on a progress dialog.
 class UserException final : public AudacityException
 {
 public: