Fixup per review

svn path=/trunk/netsurf/; revision=10196

content/llcache.c

@@ -199,13 +199,7 @@ static nserror llcache_fetch_cert_error(llcache_object *object,
  * Public API								      *
  ******************************************************************************/
 
-/**
+/* See llcache.h for documentation */
- * Initialise the low-level cache
- *
- * \param cb  Query handler
- * \param pw  Pointer to query handler data
- * \return NSERROR_OK on success, appropriate error otherwise.
- */
 nserror llcache_initialise(llcache_query_callback cb, void *pw)
 {
 	query_cb = cb;
@@ -214,11 +208,7 @@ nserror llcache_initialise(llcache_query_callback cb, void *pw)
 	return NSERROR_OK;
 }
 
-/**
+/* See llcache.h for documentation */
- * Poll the low-level cache
- *
- * \return NSERROR_OK on success, appropriate error otherwise.
- */
 nserror llcache_poll(void)
 {
 	llcache_object *object;
@@ -242,18 +232,7 @@ nserror llcache_poll(void)
 	return NSERROR_OK;
 }
 
-/**
+/* See llcache.h for documentation */
- * Retrieve a handle for a low-level cache object
- *
- * \param url	   URL of the object to fetch
- * \param flags	   Object retrieval flags
- * \param referer  Referring URL, or NULL if none
- * \param post	   POST data, or NULL for a GET request
- * \param cb	   Client callback for events
- * \param pw	   Pointer to client-specific data
- * \param result   Pointer to location to recieve cache handle
- * \return NSERROR_OK on success, appropriate error otherwise
- */
 nserror llcache_handle_retrieve(const char *url, uint32_t flags,
 		const char *referer, const llcache_post_data *post,
 		llcache_handle_callback cb, void *pw,
@@ -288,14 +267,7 @@ nserror llcache_handle_retrieve(const char *url, uint32_t flags,
 	return NSERROR_OK;
 }
 
-/**
+/* See llcache.h for documentation */
- * Change the callback associated with a low-level cache handle
- *
- * \param handle  Handle to change callback of
- * \param cb	  New callback
- * \param pw	  Client data for new callback
- * \return NSERROR_OK on success, appropriate error otherwise
- */
 nserror llcache_handle_change_callback(llcache_handle *handle,
 		llcache_handle_callback cb, void *pw)
 {
@@ -305,12 +277,7 @@ nserror llcache_handle_change_callback(llcache_handle *handle,
 	return NSERROR_OK;
 }
 
-/**
+/* See llcache.h for documentation */
- * Release a low-level cache handle
- *
- * \param handle  Handle to release
- * \return NSERROR_OK on success, appropriate error otherwise
- */
 nserror llcache_handle_release(llcache_handle *handle)
 {
 	nserror error = NSERROR_OK;
@@ -330,24 +297,13 @@ nserror llcache_handle_release(llcache_handle *handle)
 	return error; 
 }
 
-/**
+/* See llcache.h for documentation */
- * Retrieve the post-redirect URL of a low-level cache object
- *
- * \param handle  Handle to retrieve URL from
- * \return Post-redirect URL of cache object
- */
 const char *llcache_handle_get_url(const llcache_handle *handle)
 {
 	return handle->object != NULL ? handle->object->url : NULL;
 }
 
-/**
+/* See llcache.h for documentation */
- * Retrieve source data of a low-level cache object
- *
- * \param handle  Handle to retrieve source data from
- * \param size	  Pointer to location to receive byte length of data
- * \return Pointer to source data
- */
 const uint8_t *llcache_handle_get_source_data(const llcache_handle *handle,
 		size_t *size)
 {
@@ -356,18 +312,7 @@ const uint8_t *llcache_handle_get_source_data(const llcache_handle *handle,
 	return handle->object != NULL ? handle->object->source_data : NULL;
 }
 
-/**
+/* See llcache.h for documentation */
- * Retrieve a header value associated with a low-level cache object
- *
- * \param handle  Handle to retrieve header from
- * \param key	  Header name
- * \return Header value, or NULL if header does not exist
- *
- * \todo Make the key an enumeration, to avoid needless string comparisons
- * \todo Forcing the client to parse the header value seems wrong. 
- *	 Better would be to return the actual value part and an array of 
- *	 key-value pairs for any additional parameters.
- */
 const char *llcache_handle_get_header(const llcache_handle *handle, 
 		const char *key)
 {
@@ -386,13 +331,7 @@ const char *llcache_handle_get_header(const llcache_handle *handle,
 	return NULL;
 }
 
-/**
+/* See llcache.h for documentation */
- * Determine if the same underlying object is referenced by the given handles
- *
- * \param a  First handle
- * \param b  Second handle
- * \return True if handles reference the same object, false otherwise
- */
 bool llcache_handle_references_same_object(const llcache_handle *a, 
 		const llcache_handle *b)
 {

content/llcache.h

@@ -81,10 +81,16 @@ typedef nserror (*llcache_handle_callback)(llcache_handle *handle,
 		const llcache_event *event, void *pw);
 
 /** Flags for low-level cache object retrieval */
-#define LLCACHE_RETRIEVE_FORCE_FETCH (1 << 0) /* Force a new fetch */
+enum llcache_retrieve_flag {
-#define LLCACHE_RETRIEVE_VERIFIABLE  (1 << 1) /* Requested URL was verified */
+	/** Force a new fetch */
-#define LLCACHE_RETRIEVE_SNIFF_TYPE  (1 << 2) /* Permit content-type sniffing */
+	LLCACHE_RETRIEVE_FORCE_FETCH    = (1 << 0), 
-#define LLCACHE_RETRIEVE_NO_ERROR_PAGES (1 << 3) /* No error pages */
+	/** Requested URL was verified */
+	LLCACHE_RETRIEVE_VERIFIABLE     = (1 << 1), 
+	/** Permit content-type sniffing */
+	LLCACHE_RETRIEVE_SNIFF_TYPE     = (1 << 2), 
+	/**< No error pages */
+	LLCACHE_RETRIEVE_NO_ERROR_PAGES = (1 << 3)
+};
 
 /** Low-level cache query types */
 typedef enum {
@@ -150,7 +156,9 @@ typedef nserror (*llcache_query_callback)(const llcache_query *query, void *pw,
 nserror llcache_initialise(llcache_query_callback cb, void *pw);
 
 /**
- * Poll the low-level cache
+ * Cause the low-level cache to emit any pending notifications 
+ * and attempt to clean the cache. No guarantee is made about
+ * what, if any, cache cleaning will occur.
  *
  * \return NSERROR_OK on success, appropriate error otherwise.
  */
@@ -221,6 +229,7 @@ const uint8_t *llcache_handle_get_source_data(const llcache_handle *handle,
  * \todo Forcing the client to parse the header value seems wrong. 
  *       Better would be to return the actual value part and an array of 
  *       key-value pairs for any additional parameters.
+ * \todo Deal with multiple headers of the same key (e.g. Set-Cookie)
  */
 const char *llcache_handle_get_header(const llcache_handle *handle, 
 		const char *key);