From 41ea18907530216f15a9a74ba4c2e86641e0f6a6 Mon Sep 17 00:00:00 2001 From: Paul Licameli Date: Tue, 25 Aug 2020 10:06:08 -0400 Subject: [PATCH] Doxygen commentary for subclasses of AudacityException --- src/FileException.cpp | 15 ++++++------ src/FileException.h | 36 +++++++++++++++++---------- src/InconsistencyException.cpp | 15 ++++++------ src/InconsistencyException.h | 45 ++++++++++++++++++++++------------ src/UserException.cpp | 14 +++++------ src/UserException.h | 21 +++++++--------- 6 files changed, 84 insertions(+), 62 deletions(-) diff --git a/src/FileException.cpp b/src/FileException.cpp index 4be1b35aa..802905f2e 100644 --- a/src/FileException.cpp +++ b/src/FileException.cpp @@ -1,10 +1,11 @@ -// -// FileException.cpp -// -// -// Created by Paul Licameli on 11/22/16. -// -// +/*! + @file FileException.cpp + @brief implements FileException + + + Created by Paul Licameli on 11/22/16. + +*/ #include "Audacity.h" #include "FileException.h" diff --git a/src/FileException.h b/src/FileException.h index bb2253e3f..6c7353503 100644 --- a/src/FileException.h +++ b/src/FileException.h @@ -1,10 +1,11 @@ -// -// FileException.h -// -// -// Created by Paul Licameli on 11/22/16. -// -// +/*! + @file FileException.h + @brief MessageBoxException for failures of file operations + + + Created by Paul Licameli on 11/22/16. + +*/ #ifndef __AUDACITY_FILE_EXCEPTION__ #define __AUDACITY_FILE_EXCEPTION__ @@ -12,15 +13,24 @@ #include "AudacityException.h" #include // 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 - ( Cause cause_, const wxFileName &fileName_, - const TranslatableString &caption = XO("File Error"), - const wxFileName &renameTarget_ = {}) + explicit FileException( + Cause cause_, //!< What kind of file operation failed + const wxFileName &fileName_, //!< Which file suffered a failure + 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: diff --git a/src/InconsistencyException.cpp b/src/InconsistencyException.cpp index 5f699b3c2..e3c771590 100644 --- a/src/InconsistencyException.cpp +++ b/src/InconsistencyException.cpp @@ -1,10 +1,11 @@ -// -// InconsistencyException.cpp -// -// -// Created by Paul Licameli on 11/27/16. -// -// +/*! + @file InconsistencyException.cpp + @brief Implements InconsistencyException + + + Created by Paul Licameli on 11/27/16. + +*/ #include "Audacity.h" #include "InconsistencyException.h" diff --git a/src/InconsistencyException.h b/src/InconsistencyException.h index 81664aa4e..b87ba923f 100644 --- a/src/InconsistencyException.h +++ b/src/InconsistencyException.h @@ -1,27 +1,36 @@ -// -// InconsistencyException.h -// -// -// 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. -// +/*! + @file InconsistencyException.h + @brief MessageBoxException for violation of preconditions or assertions + + Created by Paul Licameli on 11/27/16. + +*/ #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 - ( const char *fn, const char *f, unsigned l ) + //! Don't call this directly but use @ref CONSTRUCT_INCONSISTENCY_EXCEPTION or @ref THROW_INCONSISTENCY_EXCEPTION + 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 diff --git a/src/UserException.cpp b/src/UserException.cpp index 6229bc5bb..f8e9edda8 100644 --- a/src/UserException.cpp +++ b/src/UserException.cpp @@ -1,10 +1,10 @@ -// -// UserException.cpp -// -// -// Created by Paul Licameli on 11/27/16. -// -// +/*! + @file UserException.cpp + @brief implements UserException + + Created by Paul Licameli on 11/27/16. + +*/ #include "Audacity.h" #include "UserException.h" diff --git a/src/UserException.h b/src/UserException.h index ad90b0e92..d669a72a3 100644 --- a/src/UserException.h +++ b/src/UserException.h @@ -1,21 +1,18 @@ -// -// UserException.h -// -// -// 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. -// +/*! + @file UserException.h + @brief An AudacityException with no visible message + + Created by Paul Licameli on 11/27/16. + +*/ #ifndef __AUDACITY_USER_EXCEPTION__ #define __AUDACITY_USER_EXCEPTION__ #include "AudacityException.h" -// This class does not inherit from MessageBoxException, and it does nothing -// in its delayed handler. It might be thrown after the user clicks a -// cancel button, as on a progress dialog. + //! Can be thrown when user cancels operations, as with a progress dialog. Delayed handler does nothing +/*! This class does not inherit from MessageBoxException. */ class UserException final : public AudacityException { public: