[calligra] krita/image: ApiDox for new KIS_ASSERT framework

[Dmitry Kazakov]

Git commit 08c9c53c16d0005373a6843133bfe487eead38b0 by Dmitry Kazakov.
Committed on 08/11/2013 at 14:36.
Pushed by dkazakov into branch 'master'.

ApiDox for new KIS_ASSERT framework

CC:kimageshop at kde.org

M  +59   -0    krita/image/kis_assert.h

http://commits.kde.org/calligra/08c9c53c16d0005373a6843133bfe487eead38b0

diff --git a/krita/image/kis_assert.h b/krita/image/kis_assert.h
index 08bcb98..458e038 100644
--- a/krita/image/kis_assert.h
+++ b/krita/image/kis_assert.h
@@ -27,11 +27,70 @@ KRITAIMAGE_EXPORT void kis_assert_recoverable(const char *assertion, const char
 KRITAIMAGE_EXPORT void kis_assert_x_exception(const char *assertion, const char *where, const char *what, const char *file, int line);
 
 
+/**
+ * KIS_ASSERT family of macros allows the user to choose whether to
+ * try to continue working in Krita or to abort an application and see
+ * a backtrace.
+ *
+ * Note, the macro are present in Release mode by default!
+ */
+
+/**
+ * Checks the condition and depending on the user action either aborts
+ * the program or throws an exception, which restarts event loop.
+ */
 #define KIS_ASSERT(cond) ((!(cond)) ? kis_assert_exception(#cond,__FILE__,__LINE__) : qt_noop())
+
+/**
+ * Same as KIS_ASSERT, but allows to show more text to the user.
+ *
+ * \see KIS_ASSERT
+ */
 #define KIS_ASSERT_X(cond, where, what) ((!(cond)) ? kis_assert_x_exception(#cond,where, what,__FILE__,__LINE__) : qt_noop())
+
+
+/**
+ * This is a recoverable variant of KIS_ASSERT. It doesn't throw any
+ * exceptions.  It checks the condition, and either aborts the
+ * application, or executes user-supplied code. The typical usecase is
+ * the following:
+ *
+ * int fooBar = ...;
+ * KIS_ASSERT_RECOVER (fooBar > 0) {
+ *     // the code which is executed in a case of emergency
+ * }
+ *
+ */
 #define KIS_ASSERT_RECOVER(cond) if (!(cond) && (kis_assert_recoverable(#cond,__FILE__,__LINE__), true))
+
+/**
+ * Equivalent of the following:
+ *
+ * KIS_ASSERT_RECOVER(cond) {
+ *     break;
+ * }
+ *
+ */
 #define KIS_ASSERT_RECOVER_BREAK(cond) KIS_ASSERT_RECOVER(cond) { break; }
+
+/**
+ * Equivalent of the following:
+ *
+ * KIS_ASSERT_RECOVER(cond) {
+ *     return;
+ * }
+ *
+ */
 #define KIS_ASSERT_RECOVER_RETURN(cond) KIS_ASSERT_RECOVER(cond) { return; }
+
+/**
+ * Equivalent of the following:
+ *
+ * KIS_ASSERT_RECOVER(cond) {
+ *     return val;
+ * }
+ *
+ */
 #define KIS_ASSERT_RECOVER_RETURN_VALUE(cond, val) KIS_ASSERT_RECOVER(cond) { return (val); }
 
 #endif /* __KIS_ASSERT_H */