restructure urldb source

remove forward declarations and restructure. exported functions are
also now documented in the urldb.h header.

content/urldb.h

@@ -64,62 +64,262 @@ struct cookie_data {
 
 struct bitmap;
 
-/* Destruction */
+/**
+ * Destroy urldb
+ */
 void urldb_destroy(void);
 
+
 /* Persistence support */
+
+/**
+ * Import an URL database from file, replacing any existing database
+ *
+ * \param filename Name of file containing data
+ */
 nserror urldb_load(const char *filename);
-void urldb_save(const char *filename);
+
+/**
+ * Export the current database to file
+ *
+ * \param filename Name of file to export to
+ */
+nserror urldb_save(const char *filename);
+
+/**
+ * Set the cross-session persistence of the entry for an URL
+ *
+ * \param url Absolute URL to persist
+ * \param persist True to persist, false otherwise
+ */
 void urldb_set_url_persistence(nsurl *url, bool persist);
 
+
 /* URL insertion */
+
+/**
+ * Insert an URL into the database
+ *
+ * \param url Absolute URL to insert
+ * \return true on success, false otherwise
+ */
 bool urldb_add_url(nsurl *url);
 
 
 /* URL data modification / lookup */
+
+/**
+ * Set an URL's title string, replacing any existing one
+ *
+ * \param url The URL to look for
+ * \param title The title string to use (copied)
+ */
 void urldb_set_url_title(nsurl *url, const char *title);
+
+/**
+ * Set an URL's content type
+ *
+ * \param url The URL to look for
+ * \param type The type to set
+ */
 void urldb_set_url_content_type(nsurl *url, content_type type);
+
+/**
+ * Update an URL's visit data
+ *
+ * \param url The URL to update
+ */
 void urldb_update_url_visit_data(nsurl *url);
+
+/**
+ * Reset an URL's visit statistics
+ *
+ * \param url The URL to reset
+ */
 void urldb_reset_url_visit_data(nsurl *url);
+
+/**
+ * Find data for an URL.
+ *
+ * \param url Absolute URL to look for
+ * \return Pointer to result struct, or NULL
+ */
 const struct url_data *urldb_get_url_data(nsurl *url);
+
+/**
+ * Extract an URL from the db
+ *
+ * \param url URL to extract
+ * \return Pointer to database's copy of URL or NULL if not found
+ */
 nsurl *urldb_get_url(nsurl *url);
 
+
 /* Authentication modification / lookup */
-void urldb_set_auth_details(nsurl *url, const char *realm,
-		const char *auth);
+
+/**
+ * Set authentication data for an URL
+ *
+ * \param url The URL to consider
+ * \param realm The authentication realm
+ * \param auth The authentication details (in form username:password)
+ */
+void urldb_set_auth_details(nsurl *url, const char *realm, const char *auth);
+
+/**
+ * Look up authentication details in database
+ *
+ * \param url Absolute URL to search for
+ * \param realm When non-NULL, it is realm which can be used to determine
+ *        the protection space when that's not been done before for given URL.
+ * \return Pointer to authentication details, or NULL if not found
+ */
 const char *urldb_get_auth_details(nsurl *url, const char *realm);
 
+
 /* SSL certificate permissions */
+
+/**
+ * Set certificate verification permissions
+ *
+ * \param url URL to consider
+ * \param permit Set to true to allow invalid certificates
+ */
 void urldb_set_cert_permissions(nsurl *url, bool permit);
+
+/**
+ * Retrieve certificate verification permissions from database
+ *
+ * \param url Absolute URL to search for
+ * \return true to permit connections to hosts with invalid certificates,
+ * false otherwise.
+ */
 bool urldb_get_cert_permissions(nsurl *url);
 
+
 /* Thumbnail handling */
+
+/**
+ * Set thumbnail for url, replacing any existing thumbnail
+ *
+ * \param url Absolute URL to consider
+ * \param bitmap Opaque pointer to thumbnail data, or NULL to invalidate
+ */
 void urldb_set_thumbnail(nsurl *url, struct bitmap *bitmap);
+
+/**
+ * Retrieve thumbnail data for given URL
+ *
+ * \param url Absolute URL to search for
+ * \return Pointer to thumbnail data, or NULL if not found.
+ */
 struct bitmap *urldb_get_thumbnail(nsurl *url);
 
+
 /* URL completion */
+
+/**
+ * Iterate over entries in the database which match the given prefix
+ *
+ * \param prefix Prefix to match
+ * \param callback Callback function
+ */
 void urldb_iterate_partial(const char *prefix,
-		bool (*callback)(nsurl *url,
-		const struct url_data *data));
+		bool (*callback)(nsurl *url, const struct url_data *data));
+
 
 /* Iteration */
+
+/**
+ * Iterate over all entries in database
+ *
+ * \param callback Function to callback for each entry
+ */
 void urldb_iterate_entries(bool (*callback)(nsurl *url,
 		const struct url_data *data));
+
+/**
+ * Iterate over all cookies in database
+ *
+ * \param callback Function to callback for each entry
+ */
 void urldb_iterate_cookies(bool (*callback)(const struct cookie_data *cookie));
 
-/* Debug */
-void urldb_dump(void);
 
 /* Cookies */
+
+/**
+ * Parse Set-Cookie header and insert cookie(s) into database
+ *
+ * \param header Header to parse, with Set-Cookie: stripped
+ * \param url URL being fetched
+ * \param referer Referring resource, or 0 for verifiable transaction
+ * \return true on success, false otherwise
+ */
 bool urldb_set_cookie(const char *header, nsurl *url, nsurl *referer);
+
+/**
+ * Retrieve cookies for an URL
+ *
+ * \param url URL being fetched
+ * \param include_http_only Whether to include HTTP(S) only cookies.
+ * \return Cookies string for libcurl (on heap), or NULL on error/no cookies
+ */
 char *urldb_get_cookie(nsurl *url, bool include_http_only);
+
+/**
+ * Delete a cookie
+ *
+ * \param domain The cookie's domain
+ * \param path The cookie's path
+ * \param name The cookie's name
+ */
 void urldb_delete_cookie(const char *domain, const char *path, const char *name);
+
+/**
+ * Load a cookie file into the database
+ *
+ * \param filename File to load
+ */
 void urldb_load_cookies(const char *filename);
+
+/**
+ * Save persistent cookies to file
+ *
+ * \param filename Path to save to
+ */
 void urldb_save_cookies(const char *filename);
 
 
+/* Debug */
+
+/**
+ * Dump URL database to stderr
+ */
+void urldb_dump(void);
+
+
 /* test harness only */
+
+/**
+ * Add a host to the database, creating any intermediate entries
+ *
+ * \param host Hostname to add
+ * \return Pointer to leaf node, or NULL on memory exhaustion
+ */
 struct host_part *urldb_add_host(const char *host);
+
+/**
+ * Add a path to the database, creating any intermediate entries
+ *
+ * \param scheme URL scheme associated with path
+ * \param port Port number on host associated with path
+ * \param host Host tree node to attach to
+ * \param path_query Absolute path plus query to add (freed)
+ * \param fragment URL fragment, or NULL
+ * \param url URL (fragment ignored)
+ * \return Pointer to leaf node, or NULL on memory exhaustion
+ */
 struct path_data *urldb_add_path(lwc_string *scheme, unsigned int port,
 		const struct host_part *host, char *path_query,
 		lwc_string *fragment, nsurl *url);