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 c1a96fd54b428924ca476c43e4b0e77b3433c002..f2d8c79c78ae295b8af1c59f945b4b4773cd01ce 100644 (file)
--- 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 d230a4a930daa9ad2a0e10eacb16828831c91e2b..644d4caa97a6adb722acc9b2b7f50b9da1e29414 100644 (file)
--- 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;