wal_decoder: add doc comments to the important types and methods

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,

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,
 }