Dark-Horse-Linux/dpm-core-ng
3
0
Fork 0
Code Issues Pull Requests Actions Activity

Documentation generation produces consumable output in one command

Browse Source 
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.
This commit is contained in:
Chris Punches
2026-08-15 20:19:26 -04:00
parent 17acad2b02
commit 1cd79e79f3
8 changed files with 183 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
include/dpm/core.h
View File

@@ -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