diff --git a/SDL2pp/Exception.hh b/SDL2pp/Exception.hh index 4e6b8e4..db14b4d 100644 --- a/SDL2pp/Exception.hh +++ b/SDL2pp/Exception.hh @@ -26,18 +26,82 @@ namespace SDL2pp { +//////////////////////////////////////////////////////////// +/// \brief %Exception object representing %SDL error +/// +/// \headerfile SDL2pp/Exception.hh +/// +//////////////////////////////////////////////////////////// class Exception : public std::exception { private: - const char* what_; - const char* sdl_error_; + const char* what_; ///< User-specified message + const char* sdl_error_; ///< SDL error string public: + //////////////////////////////////////////////////////////// + /// \brief Construct exception, storing result of SDL_GetError + /// + /// \param what User-specified explanatory string + /// + //////////////////////////////////////////////////////////// Exception(const char* what = ""); + + + //////////////////////////////////////////////////////////// + /// \brief Destructor + /// + //////////////////////////////////////////////////////////// virtual ~Exception() noexcept; + + //////////////////////////////////////////////////////////// + /// \brief Get explanatory string + /// + /// \returns Explanatory tring stored in the exception object + /// + //////////////////////////////////////////////////////////// const char* what() const noexcept; + + //////////////////////////////////////////////////////////// + /// \brief Get %SDL error text + /// + /// \returns Stored result of SDL_GetError() + /// + /// \see http://wiki.libsdl.org/SDL_GetError + /// + //////////////////////////////////////////////////////////// const char* GetSDLError() const noexcept; }; } #endif + +//////////////////////////////////////////////////////////// +/// \class SDL2pp::Exception +/// \ingroup generic +/// +/// Internally, libSDL2pp checks return value of each SDL2 +/// function it calls which may fail. If the function fails, +/// SDL2pp::Exception is thrown, and SDL2 error which expains +/// cause of function failure is stored in the exception and +/// may be extracted later. +/// +/// what() usually contains a name of SDL2 function which failed, +/// e.g. "SDL_Init() failed" +/// +/// Usage example: +/// \code +/// { +/// try { +/// SDL2pp::SDL sdl(SDL_INIT_VIDEO); +/// } catch (SDL2pp::Exception& e) { +/// std::cerr << "Fatal error:" +/// << e.what() // "SDL_Init failed" +/// << ", SDL error: " +/// << e.GetSDLError() // "x11 not available" +/// << std::endl; +/// } +/// } +/// \endcode +/// +////////////////////////////////////////////////////////////