1 files changed, 102 insertions, 3 deletions

diff --git a/desktop/browser_history.h b/desktop/browser_history.h
index 1aac41491..8ffb6125b 100644
--- a/desktop/browser_history.h
+++ b/desktop/browser_history.h
@@ -33,7 +33,23 @@ struct browser_window;
 struct history_entry;
 struct redraw_context;
 
+/**
+ * Create a new history tree for a browser window window.
+ *
+ * \param bw browser window to create history for.
+ *
+ * \return NSERROR_OK or appropriate error otherwise
+ */
 nserror browser_window_history_create(struct browser_window *bw);
+
+/**
+ * Clone a bw's history tree for new bw
+ *
+ * \param  existing	browser window with history to clone.
+ * \param  clone	browser window to make cloned history for.
+ *
+ * \return  NSERROR_OK or appropriate error otherwise
+ */
 nserror browser_window_history_clone(const struct browser_window *existing,
 		struct browser_window *clone);
 /**
@@ -59,20 +75,102 @@ nserror browser_window_history_add(struct browser_window *bw,
 nserror browser_window_history_update(struct browser_window *bw,
 		struct hlcache_handle *content);
 
+/**
+ * Free a history structure.
+ *
+ * \param bw The browser window to destroy the history within.
+ */
 void browser_window_history_destroy(struct browser_window *bw);
-void browser_window_history_back(struct browser_window *bw, bool new_window);
-void browser_window_history_forward(struct browser_window *bw, bool new_window);
+
+/**
+ * Go back in the history.
+ *
+ * \param bw A browser window to navigate the history in.
+ * \param new_window whether to open in new window.
+ * \return NSERROR_OK or error code on faliure.
+ */
+nserror browser_window_history_back(struct browser_window *bw, bool new_window);
+
+/**
+ * Go forward in the history.
+ *
+ * \param bw A browser window to navigate the history in.
+ * \param new_window whether to open in new window.
+ * \return NSERROR_OK or error code on faliure.
+ */
+nserror browser_window_history_forward(struct browser_window *bw, bool new_window);
+
+/**
+ * Check whether it is pssible to go back in the history.
+ *
+ * \param bw A browser window to check the history navigation in.
+ * \return true if the history can go back, false otherwise
+ */
 bool browser_window_history_back_available(struct browser_window *bw);
+
+/**
+ * Check whether it is pssible to go forwards in the history.
+ *
+ * \param bw A browser window to check the history navigation in.
+ * \return true if the history can go forwards, false otherwise
+ */
 bool browser_window_history_forward_available(struct browser_window *bw);
+
+/**
+ * Get the dimensions of a history.
+ *
+ * \param bw browser window with history object.
+ * \param width updated to width
+ * \param height updated to height
+ */
 void browser_window_history_size(struct browser_window *bw,
 		int *width, int *height);
+
+/**
+ * Redraw all of a history area.
+ *
+ * \param bw browser window with history object.
+ * \param ctx current redraw context
+ */
 bool browser_window_history_redraw(struct browser_window *bw,
 		const struct redraw_context *ctx);
+
+/**
+ * Redraw part of a history area.
+ *
+ * \param bw browser window with history object.
+ * \param x0 left X co-ordinate of redraw area
+ * \param y0 top Y co-ordinate of redraw area
+ * \param x1 right X co-ordinate of redraw area
+ * \param y1 lower Y co-ordinate of redraw area
+ * \param x start X co-ordinate on plot canvas
+ * \param y start Y co-ordinate on plot canvas
+ * \param ctx current redraw context
+ */
 bool browser_window_history_redraw_rectangle(struct browser_window *bw,
 		int x0, int y0, int x1, int y1, int x, int y,
 		const struct redraw_context *ctx);
+
+/**
+ * Handle a mouse click in a history.
+ *
+ * \param bw browser window containing history
+ * \param x click coordinate
+ * \param y click coordinate
+ * \param new_window  open a new window instead of using bw
+ * \return true if action was taken, false if click was not on an entry
+ */
 bool browser_window_history_click(struct browser_window *bw,
 		int x, int y, bool new_window);
+
+/**
+ * Determine the URL of the entry at a position.
+ *
+ * \param bw browser window containing history
+ * \param x x coordinate.
+ * \param y y coordinate.
+ * \return URL, or 0 if no entry at (x, y)
+ */
 const char *browser_window_history_position_url(struct browser_window *bw,
 		int x, int y);
 
@@ -153,8 +251,9 @@ const char *browser_window_history_entry_get_title(
  * \param  bw          browser window
  * \param  entry       entry to open
  * \param  new_window  open entry in new window
+ * \return NSERROR_OK or error code on faliure.
  */
-void browser_window_history_go(struct browser_window *bw,
+nserror browser_window_history_go(struct browser_window *bw,
 		struct history_entry *entry, bool new_window);
 
 #endif