Documentation: C API comments in include/

include/c/sk_data.h

Index: include/c/sk_data.h
diff --git a/include/c/sk_data.h b/include/c/sk_data.h
index 95b7f5eb0ba7ee5782f7c98b265d0ce3ac82ea66..694c372eafefe90d8bf88bda73ae86dcfd977e2c 100644
--- a/include/c/sk_data.h
+++ b/include/c/sk_data.h
@@ -15,15 +15,50 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Returns a new empty sk_data_t.  It must be unref'ed.
+*/
 SK_API sk_data_t* sk_data_new_empty();
+/**
+    Returns a new sk_data_t by copying the specified source data.

[reed1, 2015/09/01 17:35:15]

+= balance with a call to sk_data_unref(...) 

[hal.canary, 2015/09/01 17:39:53]

Done.

+*/
 SK_API sk_data_t* sk_data_new_with_copy(const void* src, size_t length);
+/**
+    Pass ownership of the given memory to a new sk_data_t, which will
+    call free() when the refernce count of the data goes to zero.  For
+    example:
+        size_t length = 1024;
+        void* buffer = malloc(length);
+        memset(buffer, 'X', length);
+        sk_data_t* data = sk_data_new_from_malloc(buffer, length);
+*/
 SK_API sk_data_t* sk_data_new_from_malloc(const void* memory, size_t length);
+/**
+    Returns a new sk_data_t using a subset of the data in the
+    specified source sk_data_t,
+*/
 SK_API sk_data_t* sk_data_new_subset(const sk_data_t* src, size_t offset, size_t length);
 
+/**
+    Increment the reference count on the given sk_data_t. Must be
+    balanced by a call to sk_data_unref().
+*/
 SK_API void sk_data_ref(const sk_data_t*);
+/**
+    Decrement the reference count. If the reference count is 1 before
+    the decrement, then release both the memory holding the sk_data_t
+    and the memory it is managing.  New sk_data_t are created with a
+    reference count of 1.
+*/
 SK_API void sk_data_unref(const sk_data_t*);
 
+/**
+    Returns the number of bytes stored.
+*/
 SK_API size_t sk_data_get_size(const sk_data_t*);
+/**
+    Returns the pointer to the data.
+ */
 SK_API const void* sk_data_get_data(const sk_data_t*);
 
 SK_C_PLUS_PLUS_END_GUARD