From 7dcb1a534249fc4f3ea37f6197228754fb831dd8 Mon Sep 17 00:00:00 2001
From: Harry Jeffery <harry@exec64.co.uk>
Date: Mon, 2 Sep 2019 22:47:40 +0100
Subject: source/backend: Improve comments

---
 src/backend.h          | 23 ++++++++++++++++-------
 src/backend_libnsgif.c |  2 +-
 src/source_private.h   | 11 ++++++++++-
 3 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/src/backend.h b/src/backend.h
index 85e3b34..46a8642 100644
--- a/src/backend.h
+++ b/src/backend.h
@@ -6,9 +6,17 @@
 struct imv_source;
 
 enum backend_result {
-  BACKEND_SUCCESS = 0, /* successful load */
-  BACKEND_BAD_PATH = 1, /* no such file, bad permissions, etc. */
-  BACKEND_UNSUPPORTED = 2, /* unsupported file format */
+
+  /* The backend recognises the file's data and thinks it can load it */
+  BACKEND_SUCCESS = 0,
+
+  /* Represents a bad file or path, implies that other backends would also fail
+   * and shouln't be tried.
+   */
+  BACKEND_BAD_PATH = 1,
+
+  /* There's data, but this backend doesn't understand it. */
+  BACKEND_UNSUPPORTED = 2,
 };
 
 /* A backend is responsible for taking a path, or a raw data pointer, and
@@ -16,6 +24,7 @@ enum backend_result {
  * different image library and support different image formats.
  */
 struct imv_backend {
+
   /* Name of the backend, for debug and user informational purposes */
   const char *name;
 
@@ -28,13 +37,13 @@ struct imv_backend {
   /* License the backend is used under */
   const char *license;
 
-  /* Input: path to open
-   * Output: initialises the imv_source instance passed in
+  /* Tries to open the given path. If successful, BACKEND_SUCCESS is returned
+   * and src will point to an imv_source instance for the given path.
    */
   enum backend_result (*open_path)(const char *path, struct imv_source **src);
 
-  /* Input: pointer to data and length of data
-   * Output: initialises the imv_source instance passed in
+  /* Tries to read the passed data. If successful, BACKEND_SUCCESS is returned
+   * and src will point to an imv_source instance for the given data.
    */
   enum backend_result (*open_memory)(void *data, size_t len, struct imv_source **src);
 };
diff --git a/src/backend_libnsgif.c b/src/backend_libnsgif.c
index f5fcd3a..5c5995b 100644
--- a/src/backend_libnsgif.c
+++ b/src/backend_libnsgif.c
@@ -118,7 +118,7 @@ static void next_frame(void *raw_private, struct imv_image **image, int *frameti
 
   gif_result code = gif_decode_frame(&private->gif, private->current_frame);
   if (code != GIF_OK) {
-    imv_log(IMV_DEBUG, "libnsgif: failed to decode first frame\n");
+    imv_log(IMV_DEBUG, "libnsgif: failed to decode a frame\n");
     return;
   }
 
diff --git a/src/source_private.h b/src/source_private.h
index 39b41fe..ed77534 100644
--- a/src/source_private.h
+++ b/src/source_private.h
@@ -4,17 +4,26 @@
 struct imv_image;
 struct imv_source;
 
+/* This is the interface a source needs to implement to function correctly.
+ * Backends act as a "factory" for sources by calling imv_source_create
+ * with a pointer to a static vtable, and a pointer to that implementation's
+ * private data, pre-initialised.
+ */
+
 struct imv_source_vtable {
+
   /* Loads the first frame, if successful puts output in image and duration
    * (in milliseconds) in frametime. If unsuccessful, image shall be NULL. A
    * still image should use a frametime of 0.
    */
   void (*load_first_frame)(void *private, struct imv_image **image, int *frametime);
+
   /* Loads the next frame, if successful puts output in image and duration
    * (in milliseconds) in frametime. If unsuccessful, image shall be NULL.
    */
   void (*load_next_frame)(void *private, struct imv_image **image, int *frametime);
-  /* Cleans up the private section of a source */
+
+  /* Cleans up the private data of a source */
   void (*free)(void *private);
 };
 
-- 
cgit v1.2.3