From 63822e94697503766b0ebe1814ba09639eaedaa0 Mon Sep 17 00:00:00 2001
From: James Bursa <james@netsurf-browser.org>
Date: Tue, 30 Sep 2003 20:33:45 +0000
Subject: [project @ 2003-09-30 20:33:45 by bursa] Document more files.

svn path=/import/netsurf/; revision=335
---
 content/fetchcache.c | 26 ++++++++++++++++++++++++++
 content/fetchcache.h |  7 +++++++
 content/other.c      |  4 ++++
 content/other.h      | 13 +++++++++++--
 4 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/content/fetchcache.c b/content/fetchcache.c
index 4996edd81..84ba57bda 100644
--- a/content/fetchcache.c
+++ b/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;
diff --git a/content/fetchcache.h b/content/fetchcache.h
index 29b3f8176..bd7c09933 100644
--- a/content/fetchcache.h
+++ b/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_
 
diff --git a/content/other.c b/content/other.c
index a205a23d5..a974bd8ed 100644
--- a/content/other.c
+++ b/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>
diff --git a/content/other.h b/content/other.h
index 9e1dd8792..96326a159 100644
--- a/content/other.h
+++ b/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);
-- 
cgit v1.2.3