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

Document the namespaces and the opaque handles

Browse Source 
dpm_core carries a namespace block saying what it holds and why its
members keep external linkage while staying off the export table. Each
unnamed namespace says its contents are private to that translation
unit, and the one in the info module says why it has to be unnamed
there: a module is built without hidden visibility or a version script,
so a helper with external linkage would reach that module's exports.

The three opaque handles in the public header were undocumented. What
documentation they had came from the struct definitions in
include/internal, which a consumer never sees.

EXTRACT_ANON_NSPACES was off, so the documentation on every file-private
helper was written and discarded. Doxygen also capitalizes the first
letter of a brief, which turned libdpm-core.so into Libdpm-core.so
wherever a brief opened with it; those are reworded.

Bare references to the library are replaced with the artifact name
throughout, including three in the info module's output. The
cli_info_version regex follows.
This commit is contained in:
Chris Punches
2026-08-16 01:42:04 -04:00
parent 5230ac8748
commit 50b95fb729
12 changed files with 129 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
include/internal/context.hpp
View File

@@ -1,6 +1,6 @@
/**
* @file context.hpp
* @brief The libdpm-core context: configuration, logging, module registry
* @brief The libdpm-core.so context: configuration, logging, module registry
*
* @copyright Copyright (c) 2026 SILO GROUP LLC
* @author Chris Punches <chris.punches@silogroup.org>
@@ -30,7 +30,7 @@
#include "internal/modules.hpp"
/** @brief A libdpm-core context: configuration, logging, module registry */
/** @brief A libdpm-core.so context: configuration, logging, module registry */
struct dpm_ctx {
/** Directory the .conf files were read from. */
std::string config_dir;
@@ -62,11 +62,31 @@ struct dpm_ctx {
std::string last_error;
};
/**
* @namespace dpm_core
* @brief Internal implementation of libdpm-core.so
*
* Holds what the library's translation units share with each other and
* with nothing else: the loader, the configuration reader, the error
* recorder, and the version parser. It is declared in include/internal/,
* which is never installed, so a consumer or a module cannot name any of
* it.
*
* Nothing in here reaches the export table. The library is compiled with
* hidden default symbol visibility and linked against a version script
* whose `local: *` covers everything the public declarations do not
* claim, so these keep external linkage across the library's own files
* while staying invisible outside it.
*
* Helpers used by a single translation unit belong in that file's
* unnamed namespace instead, which gives them internal linkage and keeps
* them from colliding across files.
*/
namespace dpm_core {
/**
* @brief Records a failure reason on the context
*
* @param ctx The libdpm-core context; NULL is a no-op
* @param ctx The libdpm-core.so context; NULL is a no-op
* @param msg The failure description
*/
void set_error(dpm_ctx* ctx, const std::string& msg);
@@ -77,7 +97,7 @@ namespace dpm_core {
* Parses every .conf file in the context's configuration directory
* into the context's configuration store.
*
* @param ctx The libdpm-core context
* @param ctx The libdpm-core.so context
*/
void load_config_dir(dpm_ctx* ctx);
} // namespace dpm_core