misc/string.h: add documentation

misc/cstring.h

@@ -1,5 +1,5 @@
 /**
- * @file composed_string.h
+ * @file cstring.h
  * @author Ambroz Bizjak <ambrop7@gmail.com>
  * 
  * @section LICENSE
@@ -39,8 +39,21 @@
 
 struct b_cstring_s;
 
+/**
+ * Callback function which is called by {@link b_cstring_get} to access the underlying resource.
+ * \a cstr points to the cstring being accessed, and the callback can use the userN members to
+ * retrieve any state information.
+ * \a offset is the offset from the beginning of the string; offset < cstr->length.
+ * This callback must set *\a out_length and return a pointer, representing a continuous
+ * region of the string that starts at the byte at index \a offset. Returning a region that
+ * spans past the end of the string is allowed.
+ */
 typedef const char * (*b_cstring_func) (const struct b_cstring_s *cstr, size_t offset, size_t *out_length);
 
+/**
+ * An abstract string which is not necessarily continuous. Its data can be read using
+ * {@link b_cstring_get}, which internally invokes the {@link b_cstring_func} callback.
+ */
 typedef struct b_cstring_s {
     size_t length;
     b_cstring_func func;
@@ -61,13 +74,57 @@ typedef struct b_cstring_s {
     } user3;
 } b_cstring;
 
+/**
+ * Convenience function which makes a cstring pointing to a buffer.
+ */
 static b_cstring b_cstring_make_buf (const char *data, size_t length);
+
+/**
+ * Retrieves a pointer to a continuous region of the string.
+ * \a offset specifies the starting offset of the region to retrieve, and must be < cstr.length.
+ * \a maxlen specifies the maximum length of the returned region, and must be > 0.
+ * The length of the region will be stored in *\a out_chunk_len, and it will always be > 0.
+ * It is possible that the returned region spans past the end of the string, unless limited
+ * by \a maxlen. The pointer to the region will be returned; it will point to the byte
+ * at offset exactly \a offset into the string.
+ */
 static const char * b_cstring_get (b_cstring cstr, size_t offset, size_t maxlen, size_t *out_chunk_len);
+
+/**
+ * Asserts that the range given by \a offset and \a length is valid for the string.
+ */
 static void b_cstring_assert_range (b_cstring cstr, size_t offset, size_t length);
+
+/**
+ * Copies a range to an external buffer.
+ */
 static void b_cstring_copy_to_buf (b_cstring cstr, size_t offset, size_t length, char *dest);
+
+/**
+ * Performs a memcmp-like operation on the given ranges of two cstrings.
+ */
 static int b_cstring_memcmp (b_cstring cstr1, b_cstring cstr2, size_t offset1, size_t offset2, size_t length);
+
+/**
+ * Allocates a buffer for a range and copies it. The buffer is allocated using {@link BAlloc}.
+ * An extra null byte will be appended. On failure, returns NULL.
+ */
 static char * b_cstring_strdup (b_cstring cstr, size_t offset, size_t length);
 
+/**
+ * Macro which iterates the continuous regions of a range within a cstring.
+ * For reach region, the statements in \a body are executed, in order.
+ * \a cstr is the string to be iterated.
+ * \a offset and \a length specify the range of the string to iterate; they must
+ * refer to a valid range for the string.
+ * \a rel_pos_var, \a chunk_data_var and \a chunk_length_var specify names of variables
+ * which will be available in \a body.
+ * \a rel_pos_var will hold the offset of the current continuous region, relative to the beginning.
+ * \a chunk_data_var will hold a pointer (const char *) to the beginning of the region, and
+ * \a chunk_length_var will hold its length.
+ * 
+ * See the implementation of {@link b_cstring_copy_to_buf} for a usage example.
+ */
 #define B_CSTRING_LOOP_RANGE(cstr, offset, length, rel_pos_var, chunk_data_var, chunk_length_var, body) \
 { \
     size_t rel_pos_var = 0; \
@@ -79,6 +136,10 @@ static char * b_cstring_strdup (b_cstring cstr, size_t offset, size_t length);
     } \
 }
 
+/**
+ * Like {@link B_CSTRING_LOOP_RANGE}, but iterates the entire string,
+ * i.e. offset==0 and length==cstr.length.
+ */
 #define B_CSTRING_LOOP(cstr, rel_pos_var, chunk_data_var, chunk_length_var, body) B_CSTRING_LOOP_RANGE(cstr, 0, (cstr).length, rel_pos_var, chunk_data_var, chunk_length_var, body)
 
 static const char * b_cstring__buf_func (const b_cstring *cstr, size_t offset, size_t *out_length)