docs(master): improve documentation for KV key prefixes (#744)

Enhance clarity on key-value structure and serialization details for
prefixes related to metadata sections.

Signed-off-by: guillex <guillex@leil.io>

Author: lgsilva3087

src/master/kv_common_keys.h

@@ -42,14 +42,43 @@ inline constexpr std::string_view kMetaDirNodesKey = "META_DIR_NODES";
 inline constexpr std::string_view kMetaLinkNodesKey = "META_LINK_NODES";
 
 // Metadata sections prefixes
+
+/// Prefix for FSNode entries
+/// Format: NODE_<InodeId>:<SerializedFSNodeData>
+/// @note InodeId is serialized as Big Endian to maintain numeric order in lexicographical sorting
+/// enabling efficient range queries for all nodes or specific inode ranges.
 inline constexpr std::string_view kNodeKeyPrefix = "NODE_";    // Section NODE 1.0
+
+/// Prefix for edges (directory entries)
+/// Format: EDGE_<ParentId><Name>:<ChildId>
+/// e.g.: EDGE_1999ChildName: 2535
+/// @note ParentId is serialized as Big Endian to maintain numeric order in lexicographical sorting,
+/// enabling efficient range queries for all edges of a specific parent.
+/// @note ChildId is also serialized as Big Endian.
+/// @note The in-memory implementation only needs to persist the EDGE section in metadata.sfs,
+/// but the KV implementations need additional reverse indexes for efficient lookups and traversals,
+/// which are stored as separate keys with their own prefixes (e.g., DIR_PARENT_, PARENT_).
+/// @see kEdgeLowerKeyPrefix, kDirParentKeyPrefix, kParentKeyPrefix, kDirNodesCountPrefix,
+/// kDirStatsPrefix
 inline constexpr std::string_view kEdgeKeyPrefix = "EDGE_";    // Section EDGE 1.0
+
+/// Prefix for free/reusable inode ids
+/// Format: FREE_<InodeId>:<TimeStamp>
+/// @note InodeId is serialized as Big Endian. TimeStamp is a 32-bit Big Endian value indicating
+/// when the inode was freed.
 inline constexpr std::string_view kFreeKeyPrefix = "FREE_";    // Section FREE 1.0
+
+/// Prefix for chunk entries (mostly used for chunk locking)
+/// Format: CHNK_<ChunkId><ChunkVersion>:<LockedTo><LockId>
+/// @note ChunkId (64-bit) and ChunkVersion (32-bit) are serialized as Big Endian in the key.
+/// LockedTo and LockId (both 32-bit) are also Big Endian.
+inline constexpr std::string_view kChunkKeyPrefix = "CHNK_";   // Section CHNK 1.0
+
+// Reserved for future use
 inline constexpr std::string_view kXAttrKeyPrefix = "XATR_";   // Section XATR 1.0
 inline constexpr std::string_view kACLsKeyPrefix = "ACLS_";    // Section ACLS 1.2
 inline constexpr std::string_view kQuotasKeyPrefix = "QUOT_";  // Section QUOT 1.1
 inline constexpr std::string_view kLocksKeyPrefix = "FLCK_";   // Section FLCK 1.0
-inline constexpr std::string_view kChunkKeyPrefix = "CHNK_";   // Section CHNK 1.0
 
 // Case-insensitive directory support
 
@@ -71,7 +100,7 @@ inline constexpr std::string_view kParentKeyPrefix = "PARENT_";
 /// Prefix for counting directory nodes without querying all entries
 /// Format: DIR_NODES_COUNT_<ParentId>:<DirEntriesCount>.
 /// DirEntriesCount is stored as little-endian int64_t for atomic updates.
-/// Note: Signed integers are used in FDB storage to enable simpler atomic add/subtract
+/// @note Signed integers are used in FDB storage to enable simpler atomic add/subtract
 /// operations without unsigned arithmetic underflow concerns.
 inline constexpr std::string_view kDirNodesCountPrefix = "DIR_NODES_COUNT_";
 
@@ -81,7 +110,7 @@ inline constexpr std::string_view kDirNodesCountPrefix = "DIR_NODES_COUNT_";
 /// Format: DIR_STATS_<DirId><SuffixByte>:<Value>
 /// Each directory has 8 keys with different suffix bytes for each stat field.
 /// Values are stored as little-endian int64_t for atomic updates.
-/// Note: Although StatsRecord uses unsigned types in memory, signed integers are used
+/// @note Although StatsRecord uses unsigned types in memory, signed integers are used
 /// in FDB storage to enable simpler atomic add/subtract operations without unsigned
 /// arithmetic underflow concerns. Values are converted between types during serialization.
 /// Stats are recursively aggregated (sum of all descendants) and maintained incrementally