From: Timo Sirainen <timo.sirainen@open-xchange.com>
Date: Mon, 25 Jan 2021 20:42:37 +0000 (+0200)
Subject: lib-index: Add comments to struct mail_index_ext_header and related
X-Git-Tag: 2.3.16~286
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9a71b83bdd40b6da84665291e5aa8f925763e9b9;p=thirdparty%2Fdovecot%2Fcore.git

lib-index: Add comments to struct mail_index_ext_header and related
---

diff --git a/src/lib-index/mail-index-private.h b/src/lib-index/mail-index-private.h
index c1a96fd54b..f2d8c79c78 100644
--- a/src/lib-index/mail-index-private.h
+++ b/src/lib-index/mail-index-private.h
@@ -48,6 +48,7 @@ typedef int mail_index_expunge_handler_t(struct mail_index_sync_map_ctx *ctx,
 #define MAIL_INDEX_HEADER_SIZE_ALIGN(size) \
 	(((size) + 7) & ~7U)
 
+/* In-memory copy of struct mail_index_ext_header */
 struct mail_index_ext {
 	const char *name;
 	uint32_t index_idx; /* index ext_id */
@@ -61,14 +62,27 @@ struct mail_index_ext {
 };
 
 struct mail_index_ext_header {
-	uint32_t hdr_size; /* size of data[] */
+	/* Size of data[], i.e. the extension size in header */
+	uint32_t hdr_size;
+	/* If reset_id changes, all of the extension record data is
+	   invalidated. For example with cache files reset_id must match the
+	   cache header's file_seq or the cache offsets aren't valid. */
 	uint32_t reset_id;
+	/* Offset of this extension in struct mail_index_record. */
 	uint16_t record_offset;
+	/* Size of this extension in struct mail_index_record. */
 	uint16_t record_size;
+	/* Required alignment of this extension in struct mail_index_record.
+	   It's expected that record_offset is correctly aligned. This is used
+	   only when rearranging fields due to adding/removing other
+	   extensions. */
 	uint16_t record_align;
+	/* Size of name[], which contains the extension's unique name. */
 	uint16_t name_size;
-	/* unsigned char name[name_size] */
-	/* unsigned char data[hdr_size] (starting 64bit aligned) */
+	/* unsigned char name[name_size]; */
+	/* Extension header data, if any. This starts from the next 64-bit
+	   aligned offset after name[]. */
+	/* unsigned char data[hdr_size]; */
 };
 
 struct mail_index_keyword_header {
diff --git a/src/lib-index/mail-transaction-log.h b/src/lib-index/mail-transaction-log.h
index d230a4a930..644d4caa97 100644
--- a/src/lib-index/mail-transaction-log.h
+++ b/src/lib-index/mail-transaction-log.h
@@ -132,11 +132,16 @@ enum {
 	MAIL_TRANSACTION_EXT_INTRO_FLAG_NO_SHRINK = 0x01
 };
 
+/* See struct mail_index_ext_header for more explanations of these fields. */
 struct mail_transaction_ext_intro {
-	/* old extension: set ext_id. don't set name.
-	   new extension: ext_id = (uint32_t)-1. give name. */
+	/* If extension is already known to exist in the index file,
+	   set ext_id, but use empty name. If this is a new extension, set
+	   name, but use ext_id=(uint32_t)-1. */
 	uint32_t ext_id;
 	uint32_t reset_id;
+	/* Size of the extension header. When growing the header size, it's
+	   initially filled with zeros. The header can be written to with
+	   ext-hdr-update records. */
 	uint32_t hdr_size;
 	uint16_t record_size;
 	uint16_t record_align;