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/dpm/core.h

@@ -40,9 +40,10 @@ extern "C" {
 /* ------------------------------------------------------------------ */
 
 /**
- * Marks the public API visible. The library is compiled with hidden
- * default symbol visibility; these functions are its entire exported
- * surface.
+ * @brief Marks the public API visible
+ *
+ * The library is compiled with hidden default symbol visibility; the
+ * functions carrying this are its entire exported surface.
  */
 #ifndef DPM_API
 #define DPM_API __attribute__((visibility("default")))
@@ -60,11 +61,25 @@ typedef struct dpm_cursor dpm_cursor;
 /* Log levels                                                          */
 /* ------------------------------------------------------------------ */
 
+/**
+ * @brief Severity levels accepted by dpm_log()
+ *
+ * A message at a level above the context's configured level is dropped.
+ */
 enum {
+    /** Unrecoverable failure. */
     DPM_LOG_FATAL = 0,
+
+    /** Operation failed. */
     DPM_LOG_ERROR = 1,
-    DPM_LOG_WARN  = 2,
-    DPM_LOG_INFO  = 3,
+
+    /** Operation continued, something was wrong. */
+    DPM_LOG_WARN = 2,
+
+    /** Normal reporting; the default level. */
+    DPM_LOG_INFO = 3,
+
+    /** Detail for diagnosing behaviour. */
     DPM_LOG_DEBUG = 4
 };
 
@@ -73,25 +88,45 @@ enum {
 /* ------------------------------------------------------------------ */
 
 /**
- * Overrides for dpm_open(). Any field may be left NULL (or -1 for
- * log_level) to accept configuration-file values and built-in defaults.
- * Every field here is exposed as a dpm CLI flag.
+ * @brief Overrides for dpm_open()
+ *
+ * Any field may be left NULL (or -1 for log_level) to accept
+ * configuration-file values and built-in defaults. Every field here is
+ * exposed as a flag on the dpm binary.
  */
 typedef struct dpm_open_overrides {
-    const char* config_dir;   /* NULL = /etc/dpm/conf.d/               */
-    const char* module_path;  /* NULL = config value, then built-in    */
-    const char* root;         /* NULL = "/" (target root for pkg ops)  */
-    int         log_level;    /* -1 = config value; else DPM_LOG_*     */
+    /** NULL selects /etc/dpm/conf.d/. */
+    const char* config_dir;
+
+    /** NULL selects the configured value, then the built-in default. */
+    const char* module_path;
+
+    /** NULL selects "/", the target root for package operations. */
+    const char* root;
+
+    /** -1 selects the configured value; otherwise a DPM_LOG_* level. */
+    int log_level;
 } dpm_open_overrides;
 
 /* ------------------------------------------------------------------ */
 /* Module information (enumeration results)                            */
 /* ------------------------------------------------------------------ */
 
+/**
+ * @brief What the library read from a module at load
+ *
+ * Filled by dpm_module_info_of() and by dpm_cursor_next(). The string
+ * pointers remain valid until the context is closed.
+ */
 typedef struct dpm_module_info {
-    const char* name;         /* module name (filename minus .so)      */
-    const char* version;      /* module's own X.Y.Z                    */
-    const char* description;  /* one-line description                  */
+    /** Module name, its filename minus .so. */
+    const char* name;
+
+    /** The module's own X.Y.Z. */
+    const char* version;
+
+    /** One-line description. */
+    const char* description;
 } dpm_module_info;
 
 /* ------------------------------------------------------------------ */
@@ -285,17 +320,28 @@ DPM_API const char* dpm_last_error(dpm_ctx* ctx);
 /* Module contract (implemented by modules, called by libdpm-core)    */
 /* ------------------------------------------------------------------ */
 
-/*
- * Every module exports, as extern "C":
+/**
+ * @page module_contract The module contract
  *
- *   int         dpm_module_execute(dpm_ctx* ctx, const char* command,
- *                                  int argc, char** argv);
- *   const char* dpm_module_version(void);
- *   const char* dpm_module_description(void);
+ * A module is one .so in the module directory. It includes
+ * <dpm/core.h>, links -ldpm-core, and exports three reserved symbols as
+ * extern "C":
+ *
+ * @code
+ * int         dpm_module_execute(dpm_ctx* ctx, const char* command,
+ *                                int argc, char** argv);
+ * const char* dpm_module_version(void);
+ * const char* dpm_module_description(void);
+ * @endcode
+ *
+ * @section module_contract_surface The functional surface
  *
  * dpm_module_execute is the module's entire functional surface; its
  * capabilities are addressed by command string, so a module publishes
  * no headers, struct layouts, or symbols to anything that calls it.
+ * NULL or an empty command behaves as the module's help command.
+ *
+ * @section module_contract_version Version compatibility
  *
  * A module determines for itself whether it can work with the library
  * it is running against: dpm_core_version() reports the running
@@ -303,8 +349,12 @@ DPM_API const char* dpm_last_error(dpm_ctx* ctx);
  * module is built against the system-installed libdpm-core.so and is
  * responsible for being correct against it.
  *
+ * @section module_contract_validation Validation
+ *
  * The library refuses to load any module that does not validate
- * completely (see the DPM specification: load-time enforcement).
+ * completely: every reserved symbol resolves, and the version and
+ * description probes return well-formed values. A module that loads is
+ * fully valid.
  */
 
 #ifdef __cplusplus

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;
 };