File-level documentation for some of src/lib.

3 files changed, 18 insertions, 0 deletions

diff --git a/src/lib/err/backtrace.c b/src/lib/err/backtrace.c
index cded6459f7..5f5ecd3c37 100644
--- a/src/lib/err/backtrace.c
+++ b/src/lib/err/backtrace.c
@@ -11,6 +11,10 @@
  * family of functions, which are sometimes provided by libc and sometimes
  * provided by libexecinfo.  We tie into the sigaction() backend in order to
  * detect crashes.
+ *
+ * This is one of the lowest-level modules, since nearly everything needs to
+ * be able to log an error.  As such, it doesn't call the log module or any
+ * other higher-level modules directly.
  */
 
 #include "orconfig.h"
diff --git a/src/lib/err/backtrace.h b/src/lib/err/backtrace.h
index 7f77428436..70c43484f5 100644
--- a/src/lib/err/backtrace.h
+++ b/src/lib/err/backtrace.h
@@ -4,6 +4,12 @@
 #ifndef TOR_BACKTRACE_H
 #define TOR_BACKTRACE_H
 
+/**
+ * \file backtrace.h
+ *
+ * \brief Header for backtrace.c
+ **/
+
 #include "orconfig.h"
 #include "lib/cc/compat_compiler.h"
 
diff --git a/src/lib/err/torerr.c b/src/lib/err/torerr.c
index 8d8f694f1d..f9e139f967 100644
--- a/src/lib/err/torerr.c
+++ b/src/lib/err/torerr.c
@@ -9,6 +9,14 @@
  *
  * \brief Handling code for unrecoverable emergencies, at a lower level
  *   than the logging code.
+ *
+ * There are plenty of places that things can go wrong in Tor's backend
+ * libraries: the allocator can fail, the locking subsystem can fail, and so
+ * on.  But since these subsystems are used themselves by the logging module,
+ * they can't use the logging code directly to report their errors.
+ *
+ * As a workaround, the logging code provides this module with a set of raw
+ * fds to be used for reporting errors in the lowest-level Tor code.
  */
 
 #include "orconfig.h"