Documentation generation produces consumable output in one command

Building the docs target now generates the reference and leaves finished
documents in the build tree's docs directory: pdf/ holds the compiled
PDF, html/ holds the browsable reference when that format is enabled.
Doxygen and LaTeX work under docs/tmp/, which clean removes along with
the rest of the tree.

The reference has a front page and a structure. The markdown documents
in docs/ are part of the input, OVERVIEW.md becomes the landing page,
and the rest follow as chapters ahead of the namespace, class, and file
reference. The module contract, previously a plain comment block
invisible to Doxygen, is a page in its own right.

Struct and enum members throughout the headers carry documentation, on
their own lines above what they describe.

include/internal/context.hpp

@@ -32,22 +32,33 @@
 
 /** @brief A libdpm-core context: configuration, logging, module registry */
 struct dpm_ctx {
+    /** Directory the .conf files were read from. */
     std::string config_dir;
+
+    /** Directory modules are loaded from. */
     std::string module_path;
+
+    /** Target root for package operations. */
     std::string root;
 
-    int         log_level    = DPM_LOG_INFO;
-    bool        write_to_log = false;
+    /** Messages above this level are dropped. */
+    int log_level = DPM_LOG_INFO;
+
+    /** Whether to append messages to log_file. */
+    bool write_to_log = false;
+
+    /** Path of the log file. */
     std::string log_file;
 
-    /* config[module][section][key] = value */
+    /** Configuration store, addressed as config[module][section][key]. */
     std::map<std::string,
              std::map<std::string,
                       std::map<std::string, std::string>>> config;
 
-    /* validated modules, keyed by name; loaded at most once per ctx */
+    /** Validated modules keyed by name; each is loaded at most once. */
     std::map<std::string, std::unique_ptr<dpm_module>> modules;
 
+    /** Reason for the most recent failure. */
     std::string last_error;
 };
 

include/internal/modules.hpp

@@ -30,16 +30,28 @@
 
 /** @brief A loaded, fully validated module */
 struct dpm_module {
+    /** Module name, its filename minus .so. */
     std::string name;
-    void*       handle = nullptr;
+
+    /** The dlopen handle. */
+    void* handle = nullptr;
+
+    /** dpm_module_version() as read at load. */
     std::string version;
+
+    /** dpm_module_description() as read at load. */
     std::string description;
+
+    /** Resolved dpm_module_execute; the only path into module code. */
     int (*execute)(dpm_ctx*, const char*, int, char**) = nullptr;
 };
 
 /** @brief Enumeration cursor over validated modules */
 struct dpm_cursor {
+    /** One entry per valid module. */
     std::vector<dpm_module_info> infos;
+
+    /** Position of the next entry. */
     size_t idx = 0;
 };