Improve header commenting

8 files changed, 84 insertions, 9 deletions

diff --git a/src/backend.h b/src/backend.h
index 0ec7c01..85e3b34 100644
--- a/src/backend.h
+++ b/src/backend.h
@@ -12,9 +12,8 @@ enum backend_result {
 };
 
 /* A backend is responsible for taking a path, or a raw data pointer, and
- * converting that into a source that imv can handle. Each backend
- * may be powered by a different image library and support different
- * image formats.
+ * converting that into an imv_source. Each backend may be powered by a
+ * different image library and support different image formats.
  */
 struct imv_backend {
   /* Name of the backend, for debug and user informational purposes */
diff --git a/src/bitmap.h b/src/bitmap.h
index 61ef0ce..c41b8ff 100644
--- a/src/bitmap.h
+++ b/src/bitmap.h
@@ -13,7 +13,10 @@ struct imv_bitmap {
   unsigned char *data;
 };
 
+/* Copy an imv_bitmap */
 struct imv_bitmap *imv_bitmap_clone(struct imv_bitmap *bmp);
+
+/* Clean up a bitmap */
 void imv_bitmap_free(struct imv_bitmap *bmp);
 
 #endif
diff --git a/src/commands.c b/src/commands.c
index e72b9e0..5527e2e 100644
--- a/src/commands.c
+++ b/src/commands.c
@@ -5,6 +5,10 @@
 #include <stdio.h>
 #include <string.h>
 
+struct imv_commands {
+  struct list *command_list;
+};
+
 struct command {
   char* command;
   void (*handler)(struct list *args, const char *argstr, void *data);
diff --git a/src/commands.h b/src/commands.h
index cf81f68..3bd7650 100644
--- a/src/commands.h
+++ b/src/commands.h
@@ -2,16 +2,29 @@
 #define COMMANDS_H
 
 struct list;
+struct imv_commands;
 
-struct imv_commands {
-  struct list *command_list;
-};
-
+/* Create an imv_commands instance */
 struct imv_commands *imv_commands_create(void);
+
+/* Cleans up an imv_commands instance */
 void imv_commands_free(struct imv_commands *cmds);
-void imv_command_register(struct imv_commands *cmds, const char *command, void (*handler)(struct list*, const char*, void*));
+
+/* Register a new command. When a command is executed, the appropriate handler
+ * is called, with a void* for passing context.
+ */
+void imv_command_register(struct imv_commands *cmds, const char *command,
+    void (*handler)(struct list*, const char*, void*));
+
+/* Add a command alias. Any arguments provided when invoking an alias are
+ * appended to the arguments being passed to the command.
+ */
 void imv_command_alias(struct imv_commands *cmds, const char *command, const char *alias);
+
+/* Execute a single command */
 int imv_command_exec(struct imv_commands *cmds, const char *command, void *data);
+
+/* Execute a list of commands */
 int imv_command_exec_list(struct imv_commands *cmds, struct list *commands, void *data);
 
 #endif
diff --git a/src/ipc.h b/src/ipc.h
index 539b684..3b93bc3 100644
--- a/src/ipc.h
+++ b/src/ipc.h
@@ -3,17 +3,29 @@
 
 #include <unistd.h>
 
+/* imv_ipc provides a listener on a unix socket that listens for commands.
+ * When a command is received, a callback function is called.
+ */
 struct imv_ipc;
 
+/* Creates an imv_ipc instance */
 struct imv_ipc *imv_ipc_create(void);
 
+/* Cleans up an imv_ipc instance */
 void imv_ipc_free(struct imv_ipc *ipc);
 
 typedef void (*imv_ipc_callback)(const char *command, void *data);
 
+/* When a command is received, imv_ipc will call the callback function passed
+ * in. Only one callback function at a time can be connected. The data argument
+ * is passed back to the callback to allow for context passing
+ */
 void imv_ipc_set_command_callback(struct imv_ipc *ipc,
     imv_ipc_callback callback, void *data);
 
+/* Given a pid, emits the path of the unix socket that would connect to an imv
+ * instance with that pid
+ */
 void imv_ipc_path(char *buf, size_t len, int pid);
 
 #endif
diff --git a/src/list.h b/src/list.h
index 069aea1..d62f41a 100644
--- a/src/list.h
+++ b/src/list.h
@@ -4,36 +4,57 @@
 #include <stdlib.h>
 #include <string.h>
 
+/* Generic list. You know what this is. */
 struct list {
   size_t len;
   size_t cap;
   void **items;
 };
 
+/* Create a list instance */
 struct list *list_create(void);
 
+/* Clean up a list, caller should clean up contents of the list first */
 void list_free(struct list *list);
 
+/* Clean up a list, calling free() on each item first */
 void list_deep_free(struct list *list);
 
+/* Append an item to the list. Automatically resizes the list if needed */
 void list_append(struct list *list, void *item);
 
+/* Grow the list's storage to a given size, useful for avoiding unneccessary
+ * reallocations prior to inserting many items
+ */
 void list_grow(struct list *list, size_t min_size);
 
+/* Remove an item from the list at a given 0-based index */
 void list_remove(struct list *list, size_t index);
 
+/* Insert an item into the list before the given index */
 void list_insert(struct list *list, size_t index, void *item);
 
+/* Empty the list. Caller should clean up the contents of the list first */
 void list_clear(struct list *list);
 
+/* Split a null-terminated string, separating by the given delimiter.
+ * Multiple consecutive delimiters count as a single delimiter, so no empty
+ * string list items are emitted
+ */
 struct list *list_from_string(const char *string, char delim);
 
+/* Returns the index of the first item to match key, determined by the cmp
+ * function
+ */
 int list_find(
     struct list *list,
     int (*cmp)(const void *item, const void *key),
     const void *key
 );
 
+/* Assumes all list items are null-terminated strings, and concatenates them
+ * separated by sep, starting at the index given by start
+ */
 char *list_to_string(struct list *list, const char *sep, size_t start);
 
 #endif
diff --git a/src/source.h b/src/source.h
index eed95c4..d55e560 100644
--- a/src/source.h
+++ b/src/source.h
@@ -22,7 +22,10 @@ struct imv_source_message {
   const char *error;
 };
 
-/* Generic source of one or more images. Essentially a single image file */
+/* While imv_image represents a single frame of an image, be it a bitmap or
+ * vector image, imv_source represents an open handle to an image file, which
+ * can emit one or more imv_images.
+ */
 struct imv_source {
   /* usually the path of the image this is the source of */
   char *name; 
diff --git a/src/window.h b/src/window.h
index a496655..978278c 100644
--- a/src/window.h
+++ b/src/window.h
@@ -42,37 +42,57 @@ struct imv_event {
   } data;
 };
 
+/* Create a new window */
 struct imv_window *imv_window_create(int w, int h, const char *title);
 
+/* Clean up an imv_window instance */
 void imv_window_free(struct imv_window *window);
 
+/* Clears the window with the given colour */
 void imv_window_clear(struct imv_window *window, unsigned char r,
     unsigned char g, unsigned char b);
 
+/* Get the logical/event/window manager size of the window */
 void imv_window_get_size(struct imv_window *window, int *w, int *h);
 
+/* Get the pixel dimensions that the window is rendered at */
 void imv_window_get_framebuffer_size(struct imv_window *window, int *w, int *h);
 
+/* Set the window's title */
 void imv_window_set_title(struct imv_window *window, const char *title);
 
+/* Returns true if the window is fullscreen */
 bool imv_window_is_fullscreen(struct imv_window *window);
 
+/* Set the window's fullscreen state */
 void imv_window_set_fullscreen(struct imv_window *window, bool fullscreen);
 
+/* Check whether a given mouse button is pressed */
 bool imv_window_get_mouse_button(struct imv_window *window, int button);
 
+/* Gets the mouse's position */
 void imv_window_get_mouse_position(struct imv_window *window, double *x, double *y);
 
+/* Swap the framebuffers. Present anything rendered since the last call. */
 void imv_window_present(struct imv_window *window);
 
+/* Blocks until an event is received, or the timeout (in seconds) expires */
 void imv_window_wait_for_event(struct imv_window *window, double timeout);
 
+/* Push an event to the event queue. An internal copy of the event is made.
+ * Wakes up imv_window_wait_for_event */
 void imv_window_push_event(struct imv_window *window, struct imv_event *e);
 
 typedef void (*imv_event_handler)(void *data, const struct imv_event *e);
 
+/* When called, the handler function is called for each event on the event
+ * queue */
 void imv_window_pump_events(struct imv_window *window, imv_event_handler handler, void *data);
 
+/* If the current keyboard layout is known, returns a null-terminated string
+ * describing the keyboard layout and options, suitable for libxkbcommon to
+ * parse. If unknown, returns NULL.
+ */
 const char *imv_window_get_keymap(struct imv_window *window);
 
 #endif