# HG changeset patch
# User Timo Sirainen <tss@iki.fi>
# Date 1317569432 -10800
# Node ID 612b8a73ada7a991158153a5bc5988aaccb93c04
# Parent  6912969d94e8fbb3154090647596bde0f44d6ad4
mailbox list indexes: Added comment.

diff -r 6912969d94e8 -r 612b8a73ada7 src/lib-storage/list/mailbox-list-index.h
--- a/src/lib-storage/list/mailbox-list-index.h	Sun Oct 02 18:12:05 2011 +0300
+++ b/src/lib-storage/list/mailbox-list-index.h	Sun Oct 02 18:30:32 2011 +0300
@@ -1,6 +1,27 @@
 #ifndef MAILBOX_LIST_INDEX_H
 #define MAILBOX_LIST_INDEX_H
 
+/* Mailbox list index basically contains:
+
+   Header contains ID => name mapping. The name isn't the full mailbox name,
+   but rather each hierarchy level has its own ID and name. For example a
+   mailbox name "foo/bar" (with '/' as separator) would have separate IDs for
+   "foo" and "bar" names.
+
+   The records contain { parent_uid, uid, name_id } field that can be used to
+   build the whole mailbox tree. parent_uid=0 means root, otherwise it's the
+   parent node's uid.
+
+   Each record also contains GUID for each selectable mailbox. If a mailbox
+   is recreated using the same name, its GUID also changes. Note however that
+   the UID doesn't change, because the UID refers to the mailbox name, not to
+   the mailbox itself.
+
+   The records may contain also extensions for allowing mailbox_get_status()
+   to return values directly from the mailbox list index. Storage backends
+   may also add their own extensions to figure out if a record is up to date.
+*/
+
 #include "module-context.h"
 #include "mailbox-list-private.h"