Document curl stuff better.

src/ccurl_thread.c

@@ -33,11 +33,18 @@
 #include <curl/types.h>
 #include <curl/easy.h>
 
+/*
+ * The following code is the conky curl thread lib, which can be re-used to
+ * create any curl-based object (see weather and rss).  Below is an
+ * implementation of a curl-only object ($curl) which can also be used as an
+ * example.
+ */
 typedef struct _ccurl_memory_t {
 	char *memory;
 	size_t size;
 } ccurl_memory_t;
 
+/* finds a location based on uri in the list provided */
 ccurl_location_t *ccurl_find_location(ccurl_location_t **locations_head, char *uri)
 {
 	ccurl_location_t *tail = *locations_head;
@@ -68,6 +75,7 @@ ccurl_location_t *ccurl_find_location(ccurl_location_t **locations_head, char *u
 	return new;
 }
 
+/* iterates over the list provided, frees stuff (list item, uri, result) */
 void ccurl_free_locations(ccurl_location_t **locations_head)
 {
 	ccurl_location_t *tail = *locations_head;
@@ -83,6 +91,7 @@ void ccurl_free_locations(ccurl_location_t **locations_head)
 	*locations_head = 0;
 }
 
+/* callback used by curl for writing the received data */
 size_t ccurl_write_memory_callback(void *ptr, size_t size, size_t nmemb, void *data)
 {
 	size_t realsize = size * nmemb;
@@ -98,7 +107,7 @@ size_t ccurl_write_memory_callback(void *ptr, size_t size, size_t nmemb, void *d
 }
 
 
-
+/* fetch our datums */
 void ccurl_fetch_data(ccurl_location_t *curloc)
 {
 	CURL *curl = NULL;
@@ -126,13 +135,11 @@ void ccurl_fetch_data(ccurl_location_t *curloc)
 			timed_thread_unlock(curloc->p_timed_thread);
 			free(chunk.memory);
 		} else {
-			ERR("weather: no data from server");
+			ERR("curl: no data from server");
 		}
 
 		curl_easy_cleanup(curl);
 	}
-
-	return;
 }
 
 void *ccurl_thread(void *) __attribute__((noreturn));
@@ -169,18 +176,27 @@ void *ccurl_thread(void *arg)
 	/* never reached */
 }
 
+
+/*
+ * This is where the $curl section begins.
+ */
+
+/* internal location pointer for use by $curl, no touchy */
 static ccurl_location_t *ccurl_locations_head = 0;
 
+/* used to free data used by $curl */
 void ccurl_free_info(void)
 {
 	ccurl_free_locations(&ccurl_locations_head);
 }
 
+/* straight copy, used by $curl */
 void ccurl_parse_data(void *result, const char *data)
 {
 	strncpy(result, data, max_user_text);
 }
 
+/* prints result data to text buffer, used by $curl */
 void ccurl_process_info(char *p, int p_max_size, char *uri, int interval)
 {
 	ccurl_location_t *curloc = ccurl_find_location(&ccurl_locations_head, uri);
@@ -190,7 +206,7 @@ void ccurl_process_info(char *p, int p_max_size, char *uri, int interval)
 		curloc->process_function = &ccurl_parse_data;
 		ccurl_init_thread(curloc, interval);
 		if (!curloc->p_timed_thread) {
-			ERR("error setting up weather thread");
+			ERR("error setting up curl thread");
 		}
 	}
 

src/ccurl_thread.h

@@ -26,12 +26,24 @@
 
 #include "timed_thread.h"
 
+
+/* curl thread lib exports begin */
+
 typedef struct _ccurl_location_t {
-	char *uri; /* uri of location */
-	void *result; /* a pointer to some arbitrary data, will be freed by ccurl_free_info() if non-null */
-	timed_thread *p_timed_thread; /* internal thread pointer */
-	void (*process_function)(void *, const char *); /* function to call when data is ready to be processed, the first argument will be the result pointer, and the second argument is an internal buffer that shouldn't be mangled */
-	struct _ccurl_location_t *next; /* internal list pointer */
+	/* uri of location */
+	char *uri;
+	/* a pointer to some arbitrary data, will be freed by ccurl_free_info() if
+	 * non-null */
+	void *result;
+	/* internal thread pointer, destroyed by timed_thread.c */
+	timed_thread *p_timed_thread;
+	/* function to call when data is ready to be processed, the first argument
+	 * will be the result pointer, and the second argument is an internal
+	 * buffer that shouldn't be mangled */
+	void (*process_function)(void *, const char *);
+	/* internal list pointer, don't mess with this unless you don't know any
+	 * better */
+	struct _ccurl_location_t *next;
 } ccurl_location_t;
 
 /* find an existing location for the uri specified */
@@ -39,13 +51,21 @@ ccurl_location_t *ccurl_find_location(ccurl_location_t **locations_head, char *u
 /* free all locations (as well as location->uri and location->result if
  * non-null) */
 void ccurl_free_locations(ccurl_location_t **locations_head);
-/* initiates a thread at the location specified using the interval in seconds */
+/* initiates a curl thread at the location specified using the interval in
+ * seconds */
 void ccurl_init_thread(ccurl_location_t *curloc, int interval);
 
+/* curl thread lib exports end */
+
+
+/* $curl exports begin */
+
 /* for $curl, free internal list pointer */
 void ccurl_free_info(void);
 /* runs instance of $curl */
 void ccurl_process_info(char *p, int p_max_size, char *uri, int interval);
 
+/* $curl exports end */
+
 #endif /* _CURL_THREAD_H_ */