From ca8571a49b1719887b06017a6c77798bb7f3bb6b Mon Sep 17 00:00:00 2001
From: William Manley <will@williammanley.net>
Date: Fri, 22 Jun 2018 11:37:37 +0100
Subject: [PATCH] OstreeMutableTree: Document each private member of
 `OstreeMutableTree`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A prelude to my understanding.  Unfortunately `OstreeMutableTree` provides
little encapsulation, as each member has setters† so it's difficult to come
up with a list of invariants.

† `files` and `subdirs` only have getters, but the getters return mutable
  references to the internals, so we still can't reason about invariants.

Closes: #1645
Approved by: jlebon
---
 src/libostree/ostree-mutable-tree.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/libostree/ostree-mutable-tree.c b/src/libostree/ostree-mutable-tree.c
index 5cff5d82..f46e36db 100644
--- a/src/libostree/ostree-mutable-tree.c
+++ b/src/libostree/ostree-mutable-tree.c
@@ -47,10 +47,20 @@ struct OstreeMutableTree
 {
   GObject parent_instance;
 
+  /* This is the checksum of the Dirtree object that corresponds to the current
+   * contents of this directory.  contents_checksum can be NULL if the SHA was
+   * never calculated or contents of the mtree has been modified.  Even if
+   * contents_checksum is not NULL it may be out of date. */
   char *contents_checksum;
+
+  /* This is the checksum of the DirMeta object that holds the uid, gid, mode
+   * and xattrs of this directory.  This can be NULL. */
   char *metadata_checksum;
 
+  /* const char* filename -> const char* checksum */
   GHashTable *files;
+
+  /* const char* filename -> OstreeMutableTree* subtree */
   GHashTable *subdirs;
 };