Browse Source

doc: mention also how Magnum handles errors.

Or HOW IT EXPLODES STRAIGHT IN YOUR HANDS
pull/529/head
Vladimír Vondruš 5 years ago
parent
commit
2891ea3a0f
  1. 41
      doc/features.dox

41
doc/features.dox

@ -28,6 +28,8 @@ namespace Magnum {
/** @page features Feature guide /** @page features Feature guide
@brief High-level introduction to design of the Magnum library and basic building blocks. @brief High-level introduction to design of the Magnum library and basic building blocks.
@m_keywords{Features}
@tableofcontents @tableofcontents
@todoc FUCK OFF doxygen, why are you not able to link to Corrade, Corrade::Utility and Magnum/Math/ you dumb shit?! @todoc FUCK OFF doxygen, why are you not able to link to Corrade, Corrade::Utility and Magnum/Math/ you dumb shit?!
@ -115,12 +117,14 @@ are *distinct* use cases with potentially conflicting requirements (should an
enum value get written as a number? or as a name? a fully qualified name?), enum value get written as a number? or as a name? a fully qualified name?),
Magnum *doesn't* provide @cpp operator<< @ce overloads for @ref std::ostream. Magnum *doesn't* provide @cpp operator<< @ce overloads for @ref std::ostream.
Instead, there's @relativeref{Corrade,Utility::Debug}, for your typing Instead, there's @relativeref{Corrade,Utility::Debug} (and its variants,
convenience also aliased to just @ref Debug directly in the @ref Magnum @relativeref{Corrade,Utility::Warning}, @relativeref{Corrade,Utility::Error}
namespace. On its own it's able to print builtin types, all usual C++ and @relativeref{Corrade,Utility::Fatal}), for your typing convenience also
containers as well as their Corrade equivalents. Magnum then implements debug aliased to just @ref Debug / @ref Warning / @ref Error directly in the
printers for its own math types, basic structures and most enums, which get @ref Magnum namespace. On its own it's able to print builtin types, all usual
printed as fully-qualified names. For example: C++ containers as well as their Corrade equivalents. Magnum then implements
debug printers for its own math types, basic structures and most enums, which
get printed as fully-qualified names. For example:
@m_class{m-code-figure} @m_class{m-code-figure}
@ -144,6 +148,31 @@ implicitly delimited by spaces and ended with a newline, container contents
written with commas etc. Check out the class documentation for advanced written with commas etc. Check out the class documentation for advanced
features like colors, output redirection or printing file/line info. features like colors, output redirection or printing file/line info.
@section features-error-handling Error handling in Magnum
Magnum differentiates between two kinds of errors --- a programmer error (for
example an out-of-bounds access) and a runtime error (for example when a file
can't be opened). Programmer errors are assertions, directly leading to a
program abort. Runtime errors expect *you* to do the error handling, and if you
don't do that, then you're likely to hit an assertion --- a programmer error
--- shortly after.
The assertions are deliberately not recoverable and are by default
@ref CORRADE_NO_ASSERT "kept in release builds as well". A lot of effort is put
into assertion messages, which clearly show you what went wrong. They get
always printed to the standard output or its equivalent, see
the @ref troubleshooting-runtime "troubleshooting guide" for ways how to
retrieve it on various platforms.
To avoid polluting user code with excessive error handling, runtime errors are
restricted only where strictly necessary, and always documented as such. For
performance and portability reasons, exceptions aren't used, Instead, the
errors usually manifest as an invalid return value (for example an empty
@relativeref{Corrade,Containers::Optional}) and a diagnostic message
accompanying the error is printed via @relativeref{Corrade,Utility::Error}.
If needed, you can optionally
@ref Utility-Debug-scoped-output "redirect the message to a string or a log file".
@section features-examples Learn by example @section features-examples Learn by example
Before you do a deep dive into the documentation, and if you haven't done Before you do a deep dive into the documentation, and if you haven't done

Loading…
Cancel
Save