[project @ 2003-09-30 20:33:45 by bursa]

Document more files.

svn path=/import/netsurf/; revision=335

content/fetchcache.c

@@ -5,6 +5,14 @@
  * Copyright 2003 James Bursa <bursa@users.sourceforge.net>
  */
 
+/** \file
+ * High-level fetching, caching and conversion (implementation).
+ *
+ * The implementation checks the cache for the requested URL. If it is not
+ * present, a content is created and a fetch is initiated. As the status of the
+ * fetch changes and data is received, the content is updated appropriately.
+ */
+
 #include <assert.h>
 #include <string.h>
 #include "netsurf/content/cache.h"
@@ -18,6 +26,18 @@
 static void fetchcache_callback(fetch_msg msg, void *p, char *data, unsigned long size);
 
 
+/**
+ * Retrieve a URL or fetch, convert, and cache it.
+ *
+ * The referer may be 0.
+ *
+ * The caller must supply a callback function which is called when anything
+ * interesting happens to the content which is returned. See content.h.
+ *
+ * If an error occurs immediately, 0 may be returned. Later errors will be
+ * reported via the callback.
+ */
+
 struct content * fetchcache(const char *url0, char *referer,
 		void (*callback)(content_msg msg, struct content *c, void *p1,
 			void *p2, const char *error),
@@ -57,6 +77,12 @@ struct content * fetchcache(const char *url0, char *referer,
 }
 
 
+/**
+ * Callback function for fetch.
+ *
+ * This is called when the status of a fetch changes.
+ */
+
 void fetchcache_callback(fetch_msg msg, void *p, char *data, unsigned long size)
 {
 	struct content *c = p;

content/fetchcache.h

@@ -5,6 +5,13 @@
  * Copyright 2003 James Bursa <bursa@users.sourceforge.net>
  */
 
+/** \file
+ * High-level fetching, caching and conversion (interface).
+ *
+ * The fetchcache() function retrieves a URL from the cache, or fetches,
+ * converts, and caches it if not cached.
+ */
+
 #ifndef _NETSURF_DESKTOP_FETCHCACHE_H_
 #define _NETSURF_DESKTOP_FETCHCACHE_H_
 

content/other.c

@@ -5,6 +5,10 @@
  * Copyright 2003 James Bursa <bursa@users.sourceforge.net>
  */
 
+/** \file
+ * Content for unknown types (implementation).
+ */
+
 #include <assert.h>
 #include <string.h>
 #include <stdlib.h>

content/other.h

@@ -5,14 +5,23 @@
  * Copyright 2003 James Bursa <bursa@users.sourceforge.net>
  */
 
+/** \file
+ * Content for unknown types (interface).
+ *
+ * This handles ::content structures of type CONTENT_OTHER. It is used as a
+ * fallback when the MIME type of a URL is not recognised. The data is simply
+ * stored as it is received.
+ */
+
 #ifndef _NETSURF_RISCOS_OTHER_H_
 #define _NETSURF_RISCOS_OTHER_H_
 
 struct content;
 
+/** Data specific to CONTENT_OTHER. */
 struct content_other_data {
-	char *data;
-	unsigned long length;
+	char *data;		/**< Stored data. */
+	unsigned long length;	/**< Current length of stored data. */
 };
 
 void other_create(struct content *c);