Update documentation accordingly

Doxyfile

@@ -791,7 +791,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "include/" "src/"
+INPUT                  = "include/dwarfinterpret/" "src/"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

include/dwarfinterpret/DwarfInterpret.hpp

@@ -92,7 +92,14 @@ class DwarfInterpret {
         typedef uintptr_t reg_content_t;
 
 
-        /// An unwind context, holding registers
+        /** An unwind context, holding registers.
+         *
+         * The registers kept here should be enough for most of the unwinding
+         * processes. To fully emulate libunwind, we would have to save every
+         * register that is overwritten and not caller-saved.
+         *
+         * You'll most probably want to instanciate such a structure using
+         * #DwarfInterpret::get_current_unwind_context. */
         struct UnwindContext {
             // Let's pretend this is enough
             uintptr_t rip;
@@ -137,7 +144,32 @@ class DwarfInterpret {
                 const UnwindContext& ctx
                 ) const;
 
-        /// Get the current UnwindContext (from the caller's point of view)
+        /** Get the current UnwindContext (from the caller's point of view)
+         *
+         * **WARNING!** This context will be valid within the call frame of the
+         * caller, and within descendant calls from this function, but will
+         * most probably be invalid and result in weird behaviours if there is
+         * only a single `return` made!
+         *
+         * This is supposed to work:
+         * ```
+         *     void foo() {
+         *         UnwindContext context = get_current_unwind_context();
+         *         // have fun with context
+         *     }
+         * ```
+         *
+         * While this will probably crash:
+         * ```
+         *     UnwindContext wrap_get_context() {
+         *         return f(get_current_unwind_context());
+         *     }
+         *     void foo() {
+         *         UnwindContext context = wrap_get_context();
+         *         // have fun with context
+         *     }
+         * ```
+         */
         static UnwindContext get_current_unwind_context();
 
         /// Unwinds once the given context

src/DwarfInterpret.cpp

@@ -189,11 +189,6 @@ DwarfInterpret::reg_content_t DwarfInterpret::interpret_dw_register(
 }
 
 DwarfInterpret::UnwindContext DwarfInterpret::get_current_unwind_context() {
-    // FIXME for now this returns SOME unwind context (actually, the unwind
-    // context snapshot naively taken from inside this function). Unwinding
-    // it some number of times should yield the expected context
-
-
     UnwindContext ctx;
     get_cpu_register(REG_RIP, ctx.rip);
     get_cpu_register(REG_RSP, ctx.rsp);