Ever since 530e741c726a (Start preparing the API documents.,
2007-11-24) added a placeholder to describe the various APIs,
the decorate API was never documented.

Signed-off-by: Junio C Hamano <gits...@pobox.com>
 Documentation/technical/api-decorate.txt | 35 ++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/api-decorate.txt 
index 1d52a6c..0cc2b64 100644
--- a/Documentation/technical/api-decorate.txt
+++ b/Documentation/technical/api-decorate.txt
@@ -1,6 +1,37 @@
 decorate API
-Talk about <decorate.h>
+The decoration API is a mechanism to create and use a simple
+append-only hashtable to keep auxiliary information keyed by in-core
+Prepare `struct decoration deco` somewhere in-core and
+`memset(&deco, 0, sizeof(&deco))` it.  This holds your hashtable.
+`add_decoration(struct decoration *deco, const struct object *obj,
+void *decoration)` remembers `decoration` for the given `obj`.
+The function overwrites the old `decoration` for the `obj`
+registered in the hashtable with the given `decoration`, and returns
+the old value.
+The `decoration` can be of any type that can be casted to `void *`
+and it is a responsibility of the caller to typecast it to more
+appropriate type.
+Looking up
+`lookup_decoration(struct decoration *deco, const struct object *obj)`
+returns the decoration the last call to `add_decoration()` added for
+the `obj`.  You cannot tell if `obj` does not appear in the hashtable
+at all, or if `obj` has decoration whose value is NULL, so if you want
+to use the decoration API for "Did I see this object?" hashtable,
+use decoration value that is _not_ NULL.

To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to