From 0657d6815943b5350bf4a596cd826f7a9de14a90 Mon Sep 17 00:00:00 2001 From: Marcos Magueta Date: Fri, 8 May 2026 22:57:05 -0300 Subject: port docs to doxygen --- include/NamespaceReferenceManager.h | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) (limited to 'include/NamespaceReferenceManager.h') diff --git a/include/NamespaceReferenceManager.h b/include/NamespaceReferenceManager.h index d5c3897..59068f7 100644 --- a/include/NamespaceReferenceManager.h +++ b/include/NamespaceReferenceManager.h @@ -2,27 +2,31 @@ #include "Api.h" +/** + * @file NamespaceReferenceManager.h + * @brief Declares logical reference mapping and namespace isolation. + */ + namespace nt { /** * @class NamespaceReferenceManager - * * @brief Handles the logical mapping and isolation of human-readable references. * - * DESIGN NOTES: - * 1. Namespace Isolation: - * Allows for private branch shadowing (e.g., /user_a/refs/branch/abc). - * To maintain lookup clarity, protocol-level syntax must explicitly define - * the scope to prevent non-deterministic shadowing during resolution. + * Design notes: + * - Namespace isolation: allow private branch shadowing, such as + * /user_a/refs/branch/abc. To preserve lookup clarity, protocol-level + * syntax must explicitly define scope and prevent non-deterministic + * shadowing during resolution. + * + * - Multi-reference atomic updates: ensure updates to multiple references, + * such as pushing to master and audit_log simultaneously, are + * all-or-nothing. If any contention check fails, the whole batch is + * aborted to prevent partial commits and preserve audit consistency. * - * 2. Multi-Ref Atomic Updates: - * Ensures that updates to multiple references (e.g., pushing to 'master' - * and 'audit_log' simultaneously) are all-or-nothing. If any single - * contention check fails, the entire batch is aborted to prevent - * partial commits and maintain consistent audit trails. Considering we - * want to have a global access to audit, we would need to be dissociated - * from the scope of a branch, and branches are the only points of contention - * for references, so it made sense to me to think of audit as an independent branch too. + * Audit needs global access, which means it should be dissociated from a + * branch scope. Since branches are the only contention points for + * references, it makes sense to model audit as an independent branch too. */ class NT_API NamespaceReferenceManager { -- cgit v1.2.3