From 0d7d792a01a95644cceeec7d77043dfe903e783e Mon Sep 17 00:00:00 2001
From: Vlad Lazar <vlad@neon.tech>
Date: Fri, 25 Oct 2024 17:14:31 +0200
Subject: [PATCH] wal_decoder: add doc comments to the important types and
 methods

---
 libs/wal_decoder/src/decoder.rs |  7 +++++++
 libs/wal_decoder/src/models.rs  | 10 ++++++++++
 2 files changed, 17 insertions(+)

diff --git a/libs/wal_decoder/src/decoder.rs b/libs/wal_decoder/src/decoder.rs
index d9990e4a0746b..2b67020950fe3 100644
--- a/libs/wal_decoder/src/decoder.rs
+++ b/libs/wal_decoder/src/decoder.rs
@@ -1,3 +1,6 @@
+//! This module contains logic for decoding and interpreting
+//! raw bytes which represent a raw Postgres WAL record.
+
 use crate::models::*;
 use bytes::{Buf, Bytes, BytesMut};
 use pageserver_api::key::rel_block_to_key;
@@ -11,6 +14,10 @@ use postgres_ffi::{page_is_new, page_set_lsn, pg_constants, BLCKSZ};
 use utils::lsn::Lsn;
 
 impl InterpretedWalRecord {
+    /// Decode and interpreted raw bytes which represent one Postgres WAL record.
+    /// Data blocks which do not match the provided shard identity are filtered out.
+    /// Shard 0 is a special case since it tracks all relation sizes. We only give it
+    /// the keys that are being written as that is enough for updating relation sizes.
     pub fn from_bytes(
         buf: Bytes,
         shard: &ShardIdentity,
diff --git a/libs/wal_decoder/src/models.rs b/libs/wal_decoder/src/models.rs
index c7e60f0fea9df..3111890596004 100644
--- a/libs/wal_decoder/src/models.rs
+++ b/libs/wal_decoder/src/models.rs
@@ -40,11 +40,21 @@ pub enum FlushUncommittedRecords {
     No,
 }
 
+/// An interpreted Postgres WAL record, ready to be handled by the pageserver
 pub struct InterpretedWalRecord {
+    /// Optional metadata record - may cause writes to metadata keys
+    /// in the storage engine
     pub metadata_record: Option<MetadataRecord>,
+    /// Images or deltas for blocks modified in the original WAL record.
+    /// The [`Value`] is optional to avoid sending superfluous data to
+    /// shard 0 for relation size tracking.
     pub blocks: Vec<(CompactKey, Option<Value>)>,
+    /// Byte offset within WAL for the start of the original PG WAL record
     pub lsn: Lsn,
+    /// Whether to flush all uncommitted modifications to the storage engine
+    /// before ingesting this record
     pub flush_uncommitted: FlushUncommittedRecords,
+    /// Transaction id of the original PG WAL record
     pub xid: TransactionId,
 }