Add documentation to the header file

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 68 insertions, 3 deletions

diff --git a/libtracebitmap.h b/libtracebitmap.h
index 1f8b13e..144f347 100644
--- a/libtracebitmap.h
+++ b/libtracebitmap.h
@@ -5,18 +5,83 @@
 #include <stddef.h>
 #include <stdint.h>
 
+
+/**
+ * The background is show for pixels with this value
+ */
 #define LIBTRACEBITMAP_INK_OFF 0
+
+/**
+ * The foreground is show for pixels with this value
+ */
 #define LIBTRACEBITMAP_INK_ON  1
-/* Other values in (struct libtracebitmap_bitmap).image invoke undefined behaviour */
 
+
+/**
+ * Bitmap
+ */
 struct libtracebitmap_bitmap {
+	/**
+	 * The height of the bitmap, in pixels
+	 */
 	size_t height;
+
+	/**
+	 * The width of the bitmap, in pixels
+	 */
 	size_t width;
-	uint8_t *image; /* (uint8_t [.height][.width]) */
+
+	/**
+	 * The bitmap
+	 *
+	 * Row-major order oriented and non-packed, meaning
+	 * that for an y-position `y` and an x-position `x`,
+	 * `.image[y * .width + x]` returns the pixel value,
+	 * which must either be `LIBTRACEBITMAP_INK_OFF` or
+	 * `LIBTRACEBITMAP_INK_ON`
+	 */
+	uint8_t *image;
 };
 
+
+/**
+ * Vectorise a bitmap
+ *
+ * @param  bitmap              The bitmap to vectorise; `bitmap->image` will be
+ *                             be erased, but not deallocated
+ * @param  new_component       Callback function that will be called each time the function
+ *                             starts vectorising a separate component in the bitmap; the
+ *                             first argument will be the 0 if the component shall be drawn,
+ *                             and 1 if the component shall erase from a drawn component;
+ *                             the second argument will be `user_data`; assuming the bitmap
+ *                             is not empty, this will be the first callback the function calls;
+ *                             the callback function shall return 0 upon successful completion
+ *                             and any other value on failure
+ * @param  new_stop            Callback function that is called each time the function finds
+ *                             a node for the vector image; the first argument will be the
+ *                             node's y-position (0 at the top, positive downwards); the second
+ *                             argument will be the node's x-position (0 at the far left,
+ *                             positive rightwards); the third argument will be `user_data`;
+ *                             the callback function shall return 0 upon successful completion
+ *                             and any other value on failure: Lines between adjecent nodes
+ *                             within the same component (the initial and the final nodes are
+ *                             adjacent) are always either horizontal or vertical, with no
+ *                             other nodes between the them.
+ * @param  component_finished  Callback function that is called each time the function is
+ *                             finished with a component. The function will only vectorise
+ *                             one component at a time, so after calling this callback, the
+ *                             function will either return or immediate call `*new_component`,
+ *                             and after calling `*new_component`, it will never `*new_component`
+ *                             again before calling `*component_finished`; additionally,
+ *                             `*component_finished` is called once for every call to
+ *                             `*new_component`; the callback function shall return 0 upon
+ *                             successful completion and any other value on failure
+ * @param   user_data          Value to pass as the last argument for each callback function
+ * @return                     0 upon success, and the value returned by a callback function
+ *                             if it returns a non-zero value
+ */
 int libtracebitmap_trace(
-	struct libtracebitmap_bitmap *bitmap, /* image will be erased, but not deallocated */
+	struct libtracebitmap_bitmap *bitmap,
 	int (*new_component)(int negative, void *user_data),
 	int (*new_stop)(size_t y, size_t x, void *user_data),
 	int (*component_finished)(void *user_data),