remove forward refs from content/fetch.c and cleanup doc comments

1 files changed, 128 insertions, 28 deletions

diff --git a/content/fetch.h b/content/fetch.h
index a173f7f30..09b7c8d44 100644
--- a/content/fetch.h
+++ b/content/fetch.h
@@ -99,29 +99,136 @@ extern bool fetch_active;
 
 typedef void (*fetch_callback)(const fetch_msg *msg, void *p);
 
+/** @todo these calls should be in a file_table in gui_factory */
+const char *fetch_filetype(const char *unix_path);
+char *fetch_mimetype(const char *ro_path);
 
-void fetch_init(void);
-struct fetch * fetch_start(nsurl *url, nsurl *referer,
-		fetch_callback callback,
-		void *p, bool only_2xx, const char *post_urlenc,
-		const struct fetch_multipart_data *post_multipart,
-		bool verifiable, bool downgrade_tls,
-		const char *headers[]);
+
+/**
+ * Initialise the fetcher.
+ *
+ * @return NSERROR_OK or error code
+ */
+nserror fetch_init(void);
+
+/**
+ * Start fetching data for the given URL.
+ *
+ * The function returns immediately. The fetch may be queued for later
+ * processing.
+ *
+ * A pointer to an opaque struct fetch is returned, which can be passed to
+ * fetch_abort() to abort the fetch at any time. Returns NULL if memory is
+ * exhausted (or some other fatal error occurred).
+ *
+ * The caller must supply a callback function which is called when anything
+ * interesting happens. The callback function is first called with msg
+ * FETCH_HEADER, with the header in data, then one or more times
+ * with FETCH_DATA with some data for the url, and finally with
+ * FETCH_FINISHED. Alternatively, FETCH_ERROR indicates an error occurred:
+ * data contains an error message. FETCH_REDIRECT may replace the FETCH_HEADER,
+ * FETCH_DATA, FETCH_FINISHED sequence if the server sends a replacement URL.
+ *
+ */
+struct fetch *fetch_start(nsurl *url, nsurl *referer,
+			  fetch_callback callback,
+			  void *p, bool only_2xx, const char *post_urlenc,
+			  const struct fetch_multipart_data *post_multipart,
+			  bool verifiable, bool downgrade_tls,
+			  const char *headers[]);
+
+/**
+ * Abort a fetch.
+ */
 void fetch_abort(struct fetch *f);
+
+/**
+ * Do some work on current fetches.
+ *
+ * Must be called regularly to make progress on fetches.
+ */
 void fetch_poll(void);
+
+/**
+ * Clean up for quit.
+ *
+ * Must be called before exiting.
+ */
 void fetch_quit(void);
-const char *fetch_filetype(const char *unix_path);
-char *fetch_mimetype(const char *ro_path);
+
+/**
+ * Check if a URL's scheme can be fetched.
+ *
+ * \param  url  URL to check
+ * \return  true if the scheme is supported
+ */
 bool fetch_can_fetch(const nsurl *url);
+
+/**
+ * Change the callback function for a fetch.
+ */
 void fetch_change_callback(struct fetch *fetch,
-                           fetch_callback callback,
-                           void *p);
+			   fetch_callback callback,
+			   void *p);
+
+/**
+ * Get the HTTP response code.
+ */
 long fetch_http_code(struct fetch *fetch);
+
+/**
+ * Determine if a fetch was verifiable
+ *
+ * \param fetch  Fetch to consider
+ * \return Verifiable status of fetch
+ */
 bool fetch_get_verifiable(struct fetch *fetch);
 
+/**
+ * Free a linked list of fetch_multipart_data.
+ *
+ * \param list Pointer to head of list to free
+ */
 void fetch_multipart_data_destroy(struct fetch_multipart_data *list);
-struct fetch_multipart_data *fetch_multipart_data_clone(
-		const struct fetch_multipart_data *list);
+
+/**
+ * Clone a linked list of fetch_multipart_data.
+ *
+ * \param list  List to clone
+ * \return Pointer to head of cloned list, or NULL on failure
+ */
+struct fetch_multipart_data *fetch_multipart_data_clone(const struct fetch_multipart_data *list);
+
+/**
+ * send message to fetch
+ */
+void fetch_send_callback(const fetch_msg *msg, struct fetch *fetch);
+
+/**
+ * remove a queued fetch
+ */
+void fetch_remove_from_queues(struct fetch *fetch);
+
+/**
+ * Free a fetch structure and associated resources.
+ */
+void fetch_free(struct fetch *f);
+
+/**
+ * set the http code of a fetch
+ */
+void fetch_set_http_code(struct fetch *fetch, long http_code);
+
+/**
+ * get the referer from the fetch
+ */
+const char *fetch_get_referer_to_send(struct fetch *fetch);
+
+/**
+ * set cookie data on a fetch
+ */
+void fetch_set_cookie(struct fetch *fetch, const char *data);
+
 
 /* API for fetchers themselves */
 
@@ -151,20 +258,13 @@ typedef void (*fetcher_finalise)(lwc_string *scheme);
  * \return true iff success
  */
 bool fetch_add_fetcher(lwc_string *scheme,
-                       fetcher_initialise initialiser,
-                       fetcher_can_fetch can_fetch,
-                       fetcher_setup_fetch setup_fetch,
-                       fetcher_start_fetch start_fetch,
-                       fetcher_abort_fetch abort_fetch,
-                       fetcher_free_fetch free_fetch,
-                       fetcher_poll_fetcher poll_fetcher,
-                       fetcher_finalise finaliser);
-
-void fetch_send_callback(const fetch_msg *msg, struct fetch *fetch);
-void fetch_remove_from_queues(struct fetch *fetch);
-void fetch_free(struct fetch *f);
-void fetch_set_http_code(struct fetch *fetch, long http_code);
-const char *fetch_get_referer_to_send(struct fetch *fetch);
-void fetch_set_cookie(struct fetch *fetch, const char *data);
+		       fetcher_initialise initialiser,
+		       fetcher_can_fetch can_fetch,
+		       fetcher_setup_fetch setup_fetch,
+		       fetcher_start_fetch start_fetch,
+		       fetcher_abort_fetch abort_fetch,
+		       fetcher_free_fetch free_fetch,
+		       fetcher_poll_fetcher poll_fetcher,
+		       fetcher_finalise finaliser);
 
 #endif