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 <gitster@xxxxxxxxx> --- Documentation/technical/api-decorate.txt | 35 ++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/Documentation/technical/api-decorate.txt b/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 +objects. -(Linus) +Initialization +-------------- + +Prepare `struct decoration deco` somewhere in-core and +`memset(&deco, 0, sizeof(&deco))` it. This holds your hashtable. + + +Adding +------ + +`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. -- 1.8.2.1-450-gd047976 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html