use pbd's gstdio compatibility wrapper

[ardour.git] / libs / audiographer / audiographer / throwing.h

diff --git a/libs/audiographer/audiographer/throwing.h b/libs/audiographer/audiographer/throwing.h
index 05a056d5e9b52c3b4c5fe7ea061a012cb1fb5b75..ecf7aecd4934f755b67def48c352fdfd8058344a 100644 (file)
--- a/libs/audiographer/audiographer/throwing.h
+++ b/libs/audiographer/audiographer/throwing.h
@@ -5,21 +5,42 @@
 #define DEFAULT_THROW_LEVEL ThrowStrict
 #endif
 
+#include "audiographer/visibility.h"
+
 namespace AudioGrapher
 {
 
-enum ThrowLevel
+/** Compile time defined throw level.
+  * Throw levels less than ThrowStrict should be used with caution.
+  * Not throwing could mean getting a segfault.
+  * However, if you want ultra-optimized code and/or don't care about handling
+  * error situations, feel free to use whatever you want.
+  */
+enum /*LIBAUDIOGRAPHER_API*/ ThrowLevel
 {
-       ThrowNone,     //< Not allowed to throw
-       ThrowObject,   //< Object level stuff, ctors, initalizers etc.
-       ThrowProcess,  //< Process cycle level stuff
-       ThrowStrict,   //< Stricter checks than ThrowProcess, less than ThrowSample
-       ThrowSample    //< Sample level stuff
+       ThrowNone,     ///< Not allowed to throw
+       ThrowObject,   ///< Object level stuff, ctors, initalizers etc.
+       ThrowProcess,  ///< Process cycle level stuff
+       ThrowStrict,   ///< Stricter checks than ThrowProcess, less than ThrowSample
+       ThrowSample    ///< Sample level stuff
 };
 
-/// Class that allows optimizing out error checking during compile time
+/** Class that allows optimizing out error checking during compile time.
+  * Usage: to take all advantage of this class you should wrap all 
+  * throwing statemets like this:
+  * \code
+  * if (throw_level (SomeThrowLevel) && other_optional_conditionals) {
+  *    throw Exception (...);
+  * }
+  * \endcode
+  *
+  * The order of the conditionals in the if-clause is important.
+  * The checks specified in \a other_optional_conditionals are only
+  * optimized out if \a throw_level() is placed before it with a
+  * logical and (short-circuiting).
+  */
 template<ThrowLevel L = DEFAULT_THROW_LEVEL>
-class Throwing
+class /*LIBAUDIOGRAPHER_API*/ Throwing
 {
   protected:
        Throwing() {}