Docs for util.js.h.

src/util.js.h

@@ -10,24 +10,134 @@
 
 #include <stdbool.h>
 
+/**
+** Register utility script functions.
+** @param context The JS context.
+*/
 void tf_util_register(JSContext* context);
+
+/**
+** Convert UTF-8 bytes in a buffer or Uint8Array or similar to a String.
+** @param context The JS context.
+** @param value The UTF-8 bytes.
+** @return A string representation of the data interpreted as UTF-8 bytes.
+*/
 JSValue tf_util_utf8_decode(JSContext* context, JSValue value);
+
+/**
+** Get the data from what might be an ArrayBuffer.
+** @param context The JS context.
+** @param[out] psize The size of the data in bytes.
+** @param obj The object which might be an ArrayBuffer.
+** @return The ArrayBuffer's data.
+*/
 uint8_t* tf_util_try_get_array_buffer(JSContext* context, size_t* psize, JSValueConst obj);
+
+/**
+** Get the ArrayBuffer from what might be a typed ArrayBuffer.
+** @param context The JS context.
+** @param obj The object which might be a typed ArrayBuffer.
+** @param[out] pbyte_offset The offset into the buffer at which the typed ArrayBuffer starts.
+** @param[out] pbyte_length The length of the buffer.
+** @param[out] pbytes_per_element Element size in bytes.
+** @return An ArrayBuffer if obj was a typed ArrayBuffer.
+*/
 JSValue tf_util_try_get_typed_array_buffer(JSContext* context, JSValueConst obj, size_t* pbyte_offset, size_t* pbyte_length, size_t* pbytes_per_element);
+
+/**
+** Print an error and message the owning task if possible.
+** @param context The JS context.
+** @param value The value which might be an exception.
+** @return true If the value was an exception and an error was reported.
+*/
 bool tf_util_report_error(JSContext* context, JSValue value);
+
+/**
+** Get the length of an array.
+** @param context The JS context.
+** @param value An array with a "length" field.
+** @return The array's length.
+*/
 int tf_util_get_length(JSContext* context, JSValue value);
+
+/**
+** Get the index at which to insert into an array in order to preserve sorted order.
+** @param key The key being inserted.
+** @param base The beginning of the array.
+** @param count The number of elements in the array.
+** @param size The size of a single element of the array.
+** @param compare A comparison function comparing key and an element of the array.
+** @return The index at which to insert key in the array, between 0 and count inclusive.
+*/
 int tf_util_insert_index(const void* key, const void* base, size_t count, size_t size, int (*compare)(const void*, const void*));
+
+/**
+** Create a Uint8Array from bytes.
+** @param context The JS context.
+** @param data The bytes.
+** @param size The number of bytes in data.
+** @return The created array.
+*/
 JSValue tf_util_new_uint8_array(JSContext* context, const uint8_t* data, size_t size);
 
+/**
+** Base64-encode data.
+** @param source The source data.
+** @param source_length The length of the source data.
+** @param[out] out A buffer to receive the encoded data.
+** @param out_length The size of the buffer to receive encoded data.
+** @return The size of the encoded data.
+*/
 size_t tf_base64_encode(const uint8_t* source, size_t source_length, char* out, size_t out_length);
+
+/**
+** Base64-decode data.
+** @param source The source data.
+** @param source_length The length of the source data.
+** @param[out] out A buffer to receipve the decoded data.
+** @param out_length The size of the buffer to receive decoded data.
+** @return The size of the decoded data.
+*/
 size_t tf_base64_decode(const char* source, size_t source_length, uint8_t* out, size_t out_length);
 
+/**
+** Capture a stack backtrace of the calling thread.
+** @param[out] buffer A buffer with at least count element to receive the backtrace.
+** @param count The size of buffer.
+** @return The numbef of captured frames.
+*/
 int tf_util_backtrace(void** buffer, int count);
+
+/**
+** Convert a stack backtrace to string.
+** @param buffer A stack backtrace.
+** @param count The number of elements in the backtrace.
+** @return A string representation of the stack backtrace with function names,
+** files, and line numbers, as possible.  Must be freed with tf_free() by the
+** caller.
+*/
 const char* tf_util_backtrace_to_string(void* const* buffer, int count);
+
+/**
+** Capture a stack backtrace of the calling thread and convert it immediately to string.
+** @return A string representation of the stack backtrace with function names,
+** files, and line numbers, as possible.  Must be freed with tf_free() by the
+** caller.
+*/
 const char* tf_util_backtrace_string();
 
+/**
+** Convert a function pointer to its name, if possible.
+** @return The function name or null.
+*/
 const char* tf_util_function_to_string(void* function);
 
+/**
+** Get the minimum of two values.
+** @param a The first value.
+** @param b The second value.
+** @return The minimum of a and b.
+*/
 #define tf_min(a, b) \
 	({ \
 		__typeof__(a) _a = (a); \