Add in-code documentation and Doxygen settings

.gitignore

@@ -28,3 +28,4 @@
 *.out
 *.app
 
+docs

Makefile

@@ -25,3 +25,8 @@ $(TARGET): $(OBJS)
 
 clean:
 	rm -f $(OBJS) $(TARGET)
+
+docs:
+	doxygen Doxyfile
+
+.PHONY: docs

README.md

@@ -8,4 +8,13 @@ Allows the evaluation of a Dwarf register value of self at runtime. Useful for
 manual stack unwind, in the absence of a base pointer.
 
 
-**WIP**, to be documented.
+**WIP**, the documentation is probably not awesome.
+
+## Documentation
+
+To generate the documentation, make sure you have Doxygen installed on your
+computer, then run
+
+```bash
+    make docs
+```

include/DwarfInterpret.hpp

@@ -25,7 +25,7 @@ class DwarfInterpret {
      * `acquire`.
      */
 
-    public:
+    public:  // Types, sub-classes, …
         class WhatException: public std::exception {
             /** Base exception for other exceptions, not supposed to be thrown
              * by itself */
@@ -33,52 +33,93 @@ class DwarfInterpret {
             std::string what_str;
 
             public:
-                WhatException(const std::string& what): what_str(what) {}
+                /// Initialize the exception with an explanatory text chunk
+                explicit WhatException(const std::string& what)
+                    : what_str(what) {}
+
+                /// Leave the explanatory text empty
                 WhatException(): what_str("") {}
 
+                /// Get the explanatory text for this exception
                 const char* what() const noexcept {
                     return what_str.c_str();
                 }
         };
 
 
+        /// Thrown when `acquire` is called before `instanciate`
         class OF_WHAT_EXCEPTION(NotInstanciated);
+
+        /// Thrown when `instanciate` is called twice
         class OF_WHAT_EXCEPTION(AlreadyInstanciated);
+
+        /** Thrown when trying to get the value of a Dwarf register (column)
+         * that is not defined or has, somehow, no value at this PC. */
         class OF_WHAT_EXCEPTION(ValuelessRegister);
+
+        /// Thrown when accessing unimplemented parts of this library
         class OF_WHAT_EXCEPTION(NotImplemented);
+
+        /// Thrown when somehow, getcontext (read CPU registers) fails
         class OF_WHAT_EXCEPTION(FailedGetContext);
+
+        /// Thrown when a Dwarf element is not found for a given PC
         class OF_WHAT_EXCEPTION(NotFound);
 
-        typedef dwarf::core::FrameSection::register_def DwarfRegister;
-        typedef std::set<std::pair<int, DwarfRegister> > DwarfRow; // FIXME
 
+        /// A Dwarf register
+        typedef dwarf::core::FrameSection::register_def DwarfRegister;
+
+        /// A Dwarf row of registers (for a given PC)
+        typedef std::set<std::pair<int, DwarfRegister> > DwarfRow;
+
+        /// The value type of a register's contents
         typedef uintptr_t reg_content_t;
 
-    private:
-        //typedef std::set<std::pair<int, DwarfRegister> > DwarfRow;
-
-
-    public:
+    public:  // methods
         DwarfInterpret(DwarfInterpret const&) = delete;
         void operator=(DwarfInterpret const&) = delete;
 
+        /** Acquire the instance of `DwarfInterpret`. The method #instanciate
+         * must have been called beforehand.
+         *
+         * \throws NotInstanciated whenever this condition is not met.
+         */
         static DwarfInterpret& acquire();
+
+        /** Instanciate the instance of DwarfInterpret with the path to the
+         * program currently running (usually, argv[0])
+         *
+         * \throws AlreadyInstanciated if this method is called twice. */
         static DwarfInterpret& instanciate(const std::string& elf_path);
 
+        /// Returns the ELF machine number for this ELF
         int get_elf_machine() const { return elf_machine; }
 
+        /** Retrieves the value pointed to by the given Dwarf register
+         *
+         * \throws ValuelessRegister */
         reg_content_t interpret_dw_register(
                 const DwarfRow& row,
                 const DwarfRegister& reg
                 ) const;
+
+        /** Retrieves the value pointed to by the given Dwarf register
+         *
+         * \throws ValuelessRegister */
         reg_content_t interpret_dw_register(
                 const DwarfRow& row,
                 int reg_id
                 ) const;
 
+        /** Get the return address at a given program counter, assuming the
+         * correct registers are stored */
         uintptr_t get_return_address(uintptr_t cur_pc) const;
+
+        /** Get the return address of the current program point */
         uintptr_t get_self_return_address() const;
 
+        /// Get the current program counter
         static uintptr_t get_current_pc();
 
     private: