Merge branch 'jt/decorate-api'

A few structures and variables that are implementation details of
the decorate API have been renamed and then the API got documented
better.

* jt/decorate-api:
  decorate: clean up and document API

3 files changed, 85 insertions, 0 deletions

diff --git a/t/helper/.gitignore b/t/helper/.gitignore
index d02f9b39a..fff6aef22 100644
--- a/t/helper/.gitignore
+++ b/t/helper/.gitignore
@@ -8,6 +8,7 @@
 /test-dump-fsmonitor
 /test-dump-split-index
 /test-dump-untracked-cache
+/test-example-decorate
 /test-fake-ssh
 /test-scrap-cache-tree
 /test-genrandom
diff --git a/t/helper/test-example-decorate.c b/t/helper/test-example-decorate.c
new file mode 100644
index 000000000..90dc97a9d
--- /dev/null
+++ b/t/helper/test-example-decorate.c
@@ -0,0 +1,74 @@
+#include "cache.h"
+#include "object.h"
+#include "decorate.h"
+
+int cmd_main(int argc, const char **argv)
+{
+	struct decoration n;
+	struct object_id one_oid = { {1} };
+	struct object_id two_oid = { {2} };
+	struct object_id three_oid = { {3} };
+	struct object *one, *two, *three;
+
+	int decoration_a, decoration_b;
+
+	void *ret;
+
+	int i, objects_noticed = 0;
+
+	/*
+	 * The struct must be zero-initialized.
+	 */
+	memset(&n, 0, sizeof(n));
+
+	/*
+	 * Add 2 objects, one with a non-NULL decoration and one with a NULL
+	 * decoration.
+	 */
+	one = lookup_unknown_object(one_oid.hash);
+	two = lookup_unknown_object(two_oid.hash);
+	ret = add_decoration(&n, one, &decoration_a);
+	if (ret)
+		die("BUG: when adding a brand-new object, NULL should be returned");
+	ret = add_decoration(&n, two, NULL);
+	if (ret)
+		die("BUG: when adding a brand-new object, NULL should be returned");
+
+	/*
+	 * When re-adding an already existing object, the old decoration is
+	 * returned.
+	 */
+	ret = add_decoration(&n, one, NULL);
+	if (ret != &decoration_a)
+		die("BUG: when readding an already existing object, existing decoration should be returned");
+	ret = add_decoration(&n, two, &decoration_b);
+	if (ret)
+		die("BUG: when readding an already existing object, existing decoration should be returned");
+
+	/*
+	 * Lookup returns the added declarations, or NULL if the object was
+	 * never added.
+	 */
+	ret = lookup_decoration(&n, one);
+	if (ret)
+		die("BUG: lookup should return added declaration");
+	ret = lookup_decoration(&n, two);
+	if (ret != &decoration_b)
+		die("BUG: lookup should return added declaration");
+	three = lookup_unknown_object(three_oid.hash);
+	ret = lookup_decoration(&n, three);
+	if (ret)
+		die("BUG: lookup for unknown object should return NULL");
+
+	/*
+	 * The user can also loop through all entries.
+	 */
+	for (i = 0; i < n.size; i++) {
+		if (n.entries[i].base)
+			objects_noticed++;
+	}
+	if (objects_noticed != 2)
+		die("BUG: should have 2 objects");
+
+	return 0;
+}
diff --git a/t/t9004-example.sh b/t/t9004-example.sh
new file mode 100755
index 000000000..b28a028f5
--- /dev/null
+++ b/t/t9004-example.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+
+test_description='check that example code compiles and runs'
+. ./test-lib.sh
+
+test_expect_success 'decorate' '
+	test-example-decorate
+'
+
+test_done