From: Nick Mathewson <nickm@torproject.org>
Date: Thu, 7 Sep 2017 13:31:30 +0000 (-0400)
Subject: Add a module comment to util_bug.h
X-Git-Tag: tor-0.3.2.1-alpha~96
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1502bf03fdf8255d4673cc529e02ad69cef9995d;p=thirdparty%2Ftor.git

Add a module comment to util_bug.h

Closes ticket 22824.
---

diff --git a/src/common/util_bug.h b/src/common/util_bug.h
index de39317d1c..ce6565d92d 100644
--- a/src/common/util_bug.h
+++ b/src/common/util_bug.h
@@ -5,6 +5,32 @@
 
 /**
  * \file util_bug.h
+ *
+ * \brief Macros to manage assertions, fatal and non-fatal.
+ *
+ * Guidelines: All the different kinds of assertion in this file are for
+ * bug-checking only. Don't write code that can assert based on bad inputs.
+ *
+ * We provide two kinds of assertion here: "fatal" and "nonfatal". Use
+ * nonfatal assertions for any bug you can reasonably recover from -- and
+ * please, try to recover!  Many severe bugs in Tor have been caused by using
+ * a regular assertion when a nonfatal assertion would have been better.
+ *
+ * If you need to check a condition with a nonfatal assertion, AND recover
+ * from that same condition, consider using the BUG() macro inside a
+ * conditional.  For example:
+ *
+ * <code>
+ *  // wrong -- use tor_assert_nonfatal() if you just want an assertion.
+ *  BUG(ptr == NULL);
+ *
+ *  // okay, but needlessly verbose
+ *  tor_assert_nonfatal(ptr != NULL);
+ *  if (ptr == NULL) { ... }
+ *
+ *  // this is how we do it:
+ *  if (BUG(ptr == NULL)) { ... }
+ * </code>
  **/
 
 #ifndef TOR_UTIL_BUG_H