{"thread":{"id":"33429","subject":"[PATCH 1/2] decorate: document API","startedAt":"2013-04-08T06:13:43Z","lastAt":"2013-04-08T06:13:43Z","messageCount":1,"participants":["Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"213494","messageId":"7v61zx35yg.fsf@alter.siamese.dyndns.org","threadId":"33429","inReplyTo":null,"subject":"[PATCH 1/2] decorate: document API","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-08T06:13:43Z","receivedAt":"2013-04-08T06:13:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ever since 530e741c726a (Start preparing the API documents.,\n2007-11-24) added a placeholder to describe the various APIs,\nthe decorate API was never documented.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/technical/api-decorate.txt | 35 ++++++++++++++++++++++++++++++--\n 1 file changed, 33 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/api-decorate.txt b/Documentation/technical/api-decorate.txt\nindex 1d52a6c..0cc2b64 100644\n--- a/Documentation/technical/api-decorate.txt\n+++ b/Documentation/technical/api-decorate.txt\n@@ -1,6 +1,37 @@\n decorate API\n ============\n \n-Talk about <decorate.h>\n+The decoration API is a mechanism to create and use a simple\n+append-only hashtable to keep auxiliary information keyed by in-core\n+objects.\n \n-(Linus)\n+Initialization\n+--------------\n+\n+Prepare `struct decoration deco` somewhere in-core and\n+`memset(&deco, 0, sizeof(&deco))` it.  This holds your hashtable.\n+\n+\n+Adding\n+------\n+\n+`add_decoration(struct decoration *deco, const struct object *obj,\n+void *decoration)` remembers `decoration` for the given `obj`.\n+\n+The function overwrites the old `decoration` for the `obj`\n+registered in the hashtable with the given `decoration`, and returns\n+the old value.\n+\n+The `decoration` can be of any type that can be casted to `void *`\n+and it is a responsibility of the caller to typecast it to more\n+appropriate type.\n+\n+Looking up\n+----------\n+\n+`lookup_decoration(struct decoration *deco, const struct object *obj)`\n+returns the decoration the last call to `add_decoration()` added for\n+the `obj`.  You cannot tell if `obj` does not appear in the hashtable\n+at all, or if `obj` has decoration whose value is NULL, so if you want\n+to use the decoration API for \"Did I see this object?\" hashtable,\n+use decoration value that is _not_ NULL.\n-- \n1.8.2.1-450-gd047976\n"}]}