From: Behdad Esfahbod <behdad@behdad.org>
Date: Mon, 4 Oct 2010 21:22:57 +0000 (-0400)
Subject: Add API comments
X-Git-Tag: submit/2.0alpha-wayland/20121130.004132~9^2~538
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=bd361945a89ea31e6c4525aa030e18744ea81fb3;p=profile%2Fivi%2Forg.tizen.video-player.git

Add API comments
---

diff --git a/src/hb-font.h b/src/hb-font.h
index 266b74a..7815985 100644
--- a/src/hb-font.h
+++ b/src/hb-font.h
@@ -61,7 +61,19 @@ hb_face_get_reference_count (hb_face_t *face);
 void
 hb_face_destroy (hb_face_t *face);
 
-/* Returns NULL if not found */
+/* XXX
+ *
+ * I have two major concerns about this API as it is right now:
+ *
+ *   - Jonathan Kew convinced me to make it return NULL if table not found (280af1bd),
+ *     however, that is WRONG IMO.  The API should not differentiate between a non-existing
+ *     table vs a zero-length table vs a very short table.  It only leads to implementations
+ *     that check for non-NULL and assume that they've got a usable table going on...  This
+ *     actually happened with Firefox.
+ *
+ *   - It has to be renamed to reference_table() since unlike any other _get_ API, a reference
+ *     ownership transfer happens and the user is responsible to destroy the result.
+ */
 hb_blob_t *
 hb_face_get_table (hb_face_t *face,
 		   hb_tag_t   tag);
@@ -196,7 +208,8 @@ hb_font_set_funcs (hb_font_t         *font,
  *
  * The client is responsible for:
  *
- *   - Take ownership of the reference on the returned klass
+ *   - Take ownership of the reference on the returned klass,
+ *
  *   - Calling "destroy(user_data)" exactly once if returned destroy func
  *     is not NULL and the returned info is not needed anymore.
  */