Add comments to stack trace formatter and test case

Author: julianbrost

lib/base/stacktrace.cpp

@@ -14,6 +14,13 @@ using namespace icinga;
 
 std::ostream &icinga::operator<<(std::ostream &os, const StackTraceFormatter &f)
 {
+	/* In most cases, this operator<< just relies on the operator<< for the `boost::stacktrace::stacktrace` wrapped in
+	 * the `StackTraceFormatter`. But as this operator turned out to not work properly on some platforms, there is a
+	 * fallback implementation that can be enabled using the `-DICINGA2_STACKTRACE_USE_BACKTRACE_SYMBOLS` flag at
+	 * compile time. This will then switch to `backtrace_symbols()` from `<execinfo.h>` instead of the implementation
+	 * provided by Boost.
+	 */
+
 	const boost::stacktrace::stacktrace &stack = f.m_Stack;
 
 #ifdef ICINGA2_STACKTRACE_USE_BACKTRACE_SYMBOLS

lib/base/stacktrace.hpp

@@ -8,6 +8,12 @@
 namespace icinga
 {
 
+/**
+ * Formatter for `boost::stacktrace::stacktrace` objects
+ *
+ * This class wraps `boost::stacktrace::stacktrace` objects and provides an operator<<
+ * for printing them to an `std::ostream` in a custom format.
+ */
 class StackTraceFormatter {
 public:
 	StackTraceFormatter(const boost::stacktrace::stacktrace &stack) : m_Stack(stack) {}

test/base-stacktrace.cpp

@@ -6,6 +6,20 @@
 using namespace icinga;
 
 
+/* If you are reading this, you are probably doing so because this test case just failed. This might happen as it
+ * heavily depends on platform and compiler behavior. There are two likely causes why this could break:
+ *
+ *  - Your compiler found new ways to optimize the functions that are called to create a stack, even though we tried
+ *    to disable optimizations using #pragmas for some compilers. If you know a way to disable (more) optimizations for
+ *    your compiler, you can try if this helps.
+ *
+ *  - Boost fails to resolve symbol names as we've already seen on some platforms. In this case, you can try again
+ *    passing the additional flag `-DICINGA2_STACKTRACE_USE_BACKTRACE_SYMBOLS=ON` to CMake and see if this helps.
+ *
+ *  In any case, please report a bug. If you run `make CTEST_OUTPUT_ON_FAILURE=1 test`, the stack trace in question
+ *  should be printed. If it looks somewhat meaningful, you can probably ignore a failure of this test case.
+ */
+
 #pragma GCC push_options
 #pragma GCC optimize ("O0")
 #pragma clang optimize off