From 1180d1932480234619163d57a4dc2629c9309f38 Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Sun, 19 Oct 2014 19:12:55 +0100
Subject: improve documentation in headers

---
 desktop/browser.c         | 238 ++++++++++++----------------------------------
 desktop/browser.h         | 153 ++++++++++++++++++++++++++---
 desktop/browser_private.h |  20 +++-
 desktop/textinput.c       |  28 +-----
 desktop/textinput.h       |  30 ++++++
 5 files changed, 252 insertions(+), 217 deletions(-)

diff --git a/desktop/browser.c b/desktop/browser.c
index 217e8bb0b..99b25e0f6 100644
--- a/desktop/browser.c
+++ b/desktop/browser.c
@@ -459,18 +459,19 @@ char * browser_window_get_selection(struct browser_window *bw)
 	return content_get_selection(bw->selection.bw->current_content);
 }
 
-/* exported interface, documented in browser.h */
+/* exported interface, documented in desktop/browser.h */
 bool browser_window_can_search(struct browser_window *bw)
 {
 	if (bw == NULL || bw->current_content == NULL)
 		return false;
 
-	/* TODO: We shouldn't have to know about specific content types
-	 *       here.  There should be a content_is_searchable() call. */
-	if (content_get_type(bw->current_content) != CONTENT_HTML &&
-			content_get_type(bw->current_content) !=
-			CONTENT_TEXTPLAIN)
+	/** \todo We shouldn't have to know about specific content
+	 * types here. There should be a content_is_searchable() call.
+	 */
+	if ((content_get_type(bw->current_content) != CONTENT_HTML) &&
+	    (content_get_type(bw->current_content) != CONTENT_TEXTPLAIN)) {
 		return false;
+	}
 
 	return true;
 }
@@ -806,13 +807,7 @@ nserror browser_window_create(enum browser_window_create_flags flags,
 }
 
 
-/**
- * Initialise common parts of a browser window
- *
- * \param flags     Flags to control operation
- * \param bw        The window to initialise
- * \param existing  The existing window if cloning, else NULL
- */
+/* exported internal interface, documented in desktop/browser_private.h */
 nserror browser_window_initialise_common(enum browser_window_create_flags flags,
 		struct browser_window *bw, struct browser_window *existing)
 {
@@ -926,7 +921,7 @@ static bool browser_window_check_throbber(struct browser_window *bw)
 /**
  * Start the busy indicator.
  *
- * \param  bw  browser window
+ * \param bw browser window
  */
 
 static void browser_window_start_throbber(struct browser_window *bw)
@@ -945,7 +940,6 @@ static void browser_window_start_throbber(struct browser_window *bw)
  *
  * \param  bw  browser window
  */
-
 static void browser_window_stop_throbber(struct browser_window *bw)
 {
 	bw->throbbing = false;
@@ -963,7 +957,6 @@ static void browser_window_stop_throbber(struct browser_window *bw)
 /**
  * Callback for fetchcache() for browser window favicon fetches.
  */
-
 static nserror browser_window_favicon_callback(hlcache_handle *c,
 		const hlcache_event *event, void *pw)
 {
@@ -1115,7 +1108,9 @@ static void browser_window_update_favicon(hlcache_handle *c,
 	nsurl_unref(nsurl);
 }
 
-/** window callback errorcode handling */
+/**
+ * window callback errorcode handling.
+ */
 static void 
 browser_window_callback_errorcode(hlcache_handle *c,
 				  struct browser_window *bw, 
@@ -1148,9 +1143,8 @@ browser_window_callback_errorcode(hlcache_handle *c,
 /**
  * Handle meta http-equiv refresh time elapsing by loading a new page.
  *
- * \param  p  browser window to refresh with new page
+ * \param p browser window to refresh with new page
  */
-
 static void browser_window_refresh(void *p)
 {
 	struct browser_window *bw = p;
@@ -1232,7 +1226,6 @@ static void browser_window_convert_to_download(struct browser_window *bw,
 /**
  * Callback handler for content event messages.
  */
-
 static nserror browser_window_callback(hlcache_handle *c,
 		const hlcache_event *event, void *pw)
 {
@@ -1657,7 +1650,7 @@ static void browser_window_destroy_children(struct browser_window *bw)
  *
  * \param  bw  browser window
  */
-void browser_window_destroy_internal(struct browser_window *bw)
+static void browser_window_destroy_internal(struct browser_window *bw)
 {
 	assert(bw);
 
@@ -1754,30 +1747,12 @@ void browser_window_destroy_internal(struct browser_window *bw)
 			bw->status_match, bw->status_miss));
 }
 
-
-/**
- * Close and destroy a browser window.
- *
- * \param  bw  browser window
- */
-void browser_window_destroy(struct browser_window *bw)
-{
-	/* can't destoy child windows on their own */
-	assert(!bw->parent);
-
-	/* destroy */
-	browser_window_destroy_internal(bw);
-	free(bw);
-}
-
-
 /**
  * Update URL bar for a given browser window to given URL
  *
  * \param bw	Browser window to update URL bar for.
  * \param url	URL for content displayed by bw including any fragment.
  */
-
 static inline void browser_window_refresh_url_bar_internal(
 		struct browser_window *bw, nsurl *url)
 {
@@ -1793,12 +1768,18 @@ static inline void browser_window_refresh_url_bar_internal(
 }
 
 
-/**
- * Update URL bar for a given browser window to bw's content's URL
- *
- * \param bw	Browser window to update URL bar for.
- */
+/* exported interface, documented in desktop/browser.h */
+void browser_window_destroy(struct browser_window *bw)
+{
+	/* can't destoy child windows on their own */
+	assert(!bw->parent);
 
+	/* destroy */
+	browser_window_destroy_internal(bw);
+	free(bw);
+}
+
+/* exported interface, documented in desktop/browser.h */
 void browser_window_refresh_url_bar(struct browser_window *bw)
 {
 	assert(bw);
@@ -2140,15 +2121,7 @@ nserror browser_window_get_extents(struct browser_window *bw, bool scaled,
 }
 
 
-/*
- * Get the dimensions of the area a browser window occupies
- *
- * \param  bw      The browser window to get dimensions of
- * \param  width   Updated to the browser window viewport width
- * \param  height  Updated to the browser window viewport height
- * \param  scaled  Whether we want the height with scale applied
- */
-
+/* exported internal interface, documented in desktop/browser_private.h */
 void browser_window_get_dimensions(struct browser_window *bw,
 		int *width, int *height, bool scaled)
 {
@@ -2165,14 +2138,7 @@ void browser_window_get_dimensions(struct browser_window *bw,
 }
 
 
-/*
- * Set the dimensions of the area a browser window occupies
- *
- * \param  bw      The browser window to set dimensions of
- * \param  width   Width in pixels
- * \param  height  Height in pixels
- */
-
+/* Exported interface, documented in browser.h */
 void browser_window_set_dimensions(struct browser_window *bw,
 		int width, int height)
 {
@@ -2189,13 +2155,7 @@ void browser_window_set_dimensions(struct browser_window *bw,
 }
 
 
-/**
- * Redraw browser window, set extent to content, and update title.
- *
- * \param  bw		  browser_window
- * \param  scroll_to_top  move view to top of page
- */
-
+/* Exported interface, documented in browser.h */
 void browser_window_update(struct browser_window *bw, bool scroll_to_top)
 {
 	int x, y;
@@ -2277,7 +2237,7 @@ void browser_window_update(struct browser_window *bw, bool scroll_to_top)
 	}
 }
 
-
+/* Exported interface, documented in desktop/browser.h */
 void browser_window_update_box(struct browser_window *bw, struct rect *rect)
 {
 	int pos_x;
@@ -2304,13 +2264,7 @@ void browser_window_update_box(struct browser_window *bw, struct rect *rect)
 	}
 }
 
-
-/**
- * Stop all fetching activity in a browser window.
- *
- * \param  bw  browser window
- */
-
+/* Exported interface, documented in desktop/browser.h */
 void browser_window_stop(struct browser_window *bw)
 {
 	int children, index;
@@ -2351,13 +2305,7 @@ void browser_window_stop(struct browser_window *bw)
 }
 
 
-/**
- * Reload the page in a browser window.
- *
- * \param  bw  browser window
- * \param  all whether to reload all objects associated with the page
- */
-
+/* Exported interface, documented in desktop/browser.h */
 void browser_window_reload(struct browser_window *bw, bool all)
 {
 	hlcache_handle *c;
@@ -2403,13 +2351,7 @@ void browser_window_reload(struct browser_window *bw, bool all)
 }
 
 
-/**
- * Change the status bar of a browser window.
- *
- * \param  bw	 browser window
- * \param  text  new status text (copied)
- */
-
+/* Exported interface, documented in desktop/browser.h */
 void browser_window_set_status(struct browser_window *bw, const char *text)
 {
 	int text_len;
@@ -2443,13 +2385,7 @@ void browser_window_set_status(struct browser_window *bw, const char *text)
 }
 
 
-/**
- * Change the shape of the mouse pointer
- *
- * \param bw Browser window to set shape in
- * \param shape The pointer shape to use
- */
-
+/* Exported interface, documented in desktop/browser.h */
 void browser_window_set_pointer(struct browser_window *bw,
 		browser_pointer_shape shape)
 {
@@ -2495,14 +2431,8 @@ nserror browser_window_schedule_reformat(struct browser_window *bw)
 	return NSERROR_OK;
 }
 
-/**
- * Reformat a browser window contents to a new width or height.
- *
- * \param  bw      the browser window to reformat
- * \param  width   new width
- * \param  height  new height
- */
 
+/* exported function documented in desktop/browser.h */
 void browser_window_reformat(struct browser_window *bw, bool background,
 		int width, int height)
 {
@@ -2529,6 +2459,12 @@ void browser_window_reformat(struct browser_window *bw, bool background,
 	content_reformat(c, background, width, height);
 }
 
+/**
+ * Set bowser window scale.
+ *
+ * \param bw Browser window.
+ * \param scale value.
+ */
 static void browser_window_set_scale_internal(struct browser_window *bw,
 		float scale)
 {
@@ -2577,7 +2513,16 @@ float browser_window_get_scale(struct browser_window *bw)
 	return bw->scale;
 }
 
-
+/**
+ * Find browser window.
+ *
+ * \param bw Browser window.
+ * \param target Name of target.
+ * \param depth Depth to scan.
+ * \param page The browser window page.
+ * \param rdepth The rdepth.
+ * \param bw_target the output browser window.
+ */
 static void browser_window_find_target_internal(struct browser_window *bw,
 		const char *target, int depth, struct browser_window *page,
 		int *rdepth, struct browser_window **bw_target)
@@ -2623,15 +2568,7 @@ static void browser_window_find_target_internal(struct browser_window *bw,
 }
 
 
-/**
- * Locate a browser window in the specified stack according.
- *
- * \param bw  the browser_window to search all relatives of
- * \param target  the target to locate
- * \param mouse The current mouse state
- * \return The browser window the mouse is in
- */
-
+/* exported interface documented in desktop/browser.h */
 struct browser_window *browser_window_find_target(struct browser_window *bw,
 		const char *target, browser_mouse_state mouse)
 {
@@ -2779,10 +2716,9 @@ struct browser_window *browser_window_find_target(struct browser_window *bw,
  * \param  x	  coordinate of mouse
  * \param  y	  coordinate of mouse
  *
- * TODO: Remove this function, once these things are associated with content,
+ * \todo Remove this function, once these things are associated with content,
  *       rather than bw.
  */
-
 static void browser_window_mouse_drag_end(struct browser_window *bw,
 		browser_mouse_state mouse, int x, int y)
 {
@@ -2826,15 +2762,7 @@ static void browser_window_mouse_drag_end(struct browser_window *bw,
 }
 
 
-/**
- * Handle non-click mouse action in a browser window. (drag ends, movements)
- *
- * \param  bw	  browser window
- * \param  mouse  state of mouse buttons and modifier keys
- * \param  x	  coordinate of mouse
- * \param  y	  coordinate of mouse
- */
-
+/* exported interface documented in desktop/browser.h */
 void browser_window_mouse_track(struct browser_window *bw,
 		browser_mouse_state mouse, int x, int y)
 {
@@ -2982,15 +2910,7 @@ void browser_window_mouse_track(struct browser_window *bw,
 }
 
 
-/**
- * Handle mouse clicks in a browser window.
- *
- * \param  bw	  browser window
- * \param  mouse  state of mouse buttons and modifier keys
- * \param  x	  coordinate of mouse
- * \param  y	  coordinate of mouse
- */
-
+/* exported interface documented in desktop/browser.h */
 void browser_window_mouse_click(struct browser_window *bw,
 		browser_mouse_state mouse, int x, int y)
 {
@@ -3114,16 +3034,8 @@ void browser_window_mouse_click(struct browser_window *bw,
 }
 
 
-/**
- * Redraw a rectangular region of a browser window
- *
- * \param  bw	  browser window to be redrawn
- * \param  x	  x co-ord of top-left
- * \param  y	  y co-ord of top-left
- * \param  width  width of rectangle
- * \param  height height of rectangle
- */
 
+/* exported interface documented in desktop/browser.h */
 void browser_window_redraw_rect(struct browser_window *bw, int x, int y,
 		int width, int height)
 {
@@ -3131,14 +3043,7 @@ void browser_window_redraw_rect(struct browser_window *bw, int x, int y,
 }
 
 
-/**
- * Start drag scrolling the contents of the browser window
- *
- * \param bw  browser window
- * \param x   x ordinate of initial mouse position
- * \param y   y ordinate
- */
-
+/* exported interface documented in desktop/browser.h */
 void browser_window_page_drag_start(struct browser_window *bw, int x, int y)
 {
 	assert(bw != NULL);
@@ -3162,13 +3067,8 @@ void browser_window_page_drag_start(struct browser_window *bw, int x, int y)
 }
 
 
-/**
- * Check availability of Back action for a given browser window
- *
- * \param bw  browser window
- * \return true if Back action is available
- */
 
+/* exported interface documented in desktop/browser.h */
 bool browser_window_back_available(struct browser_window *bw)
 {
 	return (bw && bw->history &&
@@ -3176,40 +3076,22 @@ bool browser_window_back_available(struct browser_window *bw)
 }
 
 
-/**
- * Check availability of Forward action for a given browser window
- *
- * \param bw  browser window
- * \return true if Forward action is available
- */
 
+/* exported interface documented in desktop/browser.h */
 bool browser_window_forward_available(struct browser_window *bw)
 {
 	return (bw && bw->history &&
 			browser_window_history_forward_available(bw));
 }
 
-
-/**
- * Check availability of Reload action for a given browser window
- *
- * \param bw  browser window
- * \return true if Reload action is available
- */
-
+/* exported interface documented in desktop/browser.h */
 bool browser_window_reload_available(struct browser_window *bw)
 {
 	return (bw && bw->current_content && !bw->loading_content);
 }
 
 
-/**
- * Check availability of Stop action for a given browser window
- *
- * \param bw  browser window
- * \return true if Stop action is available
- */
-
+/* exported interface documented in desktop/browser.h */
 bool browser_window_stop_available(struct browser_window *bw)
 {
 	return (bw && (bw->loading_content ||
diff --git a/desktop/browser.h b/desktop/browser.h
index 935e2425c..e5444164e 100644
--- a/desktop/browser.h
+++ b/desktop/browser.h
@@ -33,7 +33,6 @@
 #include "desktop/frame_types.h"
 #include "desktop/mouse.h"
 
-
 struct browser_window;
 struct hlcache_handle;
 struct gui_window;
@@ -116,7 +115,7 @@ enum browser_window_nav_flags {
  *
  * \param flags		Flags to control operation
  * \param url		URL to fetch in the new window or NULL for blank
- * \param referer	The referring uri or NULL if none
+ * \param referrer	The referring uri or NULL if none
  * \param existing	The an existing bw or NULL, required for some flags.
  * \param bw		Updated to created browser window or untouched on error.
  * \return NSERROR_OK, or appropriate error otherwise.
@@ -173,7 +172,7 @@ nserror browser_window_navigate_up(struct browser_window *bw, bool new_window);
  * \param bw	  browser window
  * \return pointer to nsurl.  Doesn't create a ref for caller.
  *
- * Note: guaranteed to return a valid nsurl ptr, never returns NULL.
+ * \note guaranteed to return a valid nsurl ptr, never returns NULL.
  */
 struct nsurl* browser_window_get_url(struct browser_window *bw);
 
@@ -219,15 +218,61 @@ bool browser_window_has_content(struct browser_window *bw);
  */
 struct hlcache_handle *browser_window_get_content(struct browser_window *bw);
 
-void browser_window_get_dimensions(struct browser_window *bw,
-		int *width, int *height, bool scaled);
+/**
+ * Set the dimensions of the area a browser window occupies
+ *
+ * \param  bw      The browser window to set dimensions of
+ * \param  width   Width in pixels
+ * \param  height  Height in pixels
+ */
 void browser_window_set_dimensions(struct browser_window *bw,
 		int width, int height);
+
+/**
+ * Redraw browser window, set extent to content, and update title.
+ *
+ * \param  bw		  browser_window
+ * \param  scroll_to_top  move view to top of page
+ */
 void browser_window_update(struct browser_window *bw, bool scroll_to_top);
+
+/**
+ * update an area of a browser window.
+ *
+ * \param bw The browser window to update.
+ * \param rect The area to redraw
+ */
 void browser_window_update_box(struct browser_window *bw, struct rect *rect);
+
+/**
+ * Stop all fetching activity in a browser window.
+ *
+ * \param bw The browser window to stop activity in.
+ */
 void browser_window_stop(struct browser_window *bw);
+
+/**
+ * Reload the page in a browser window.
+ *
+ * \param  bw  browser window
+ * \param  all whether to reload all objects associated with the page
+ */
 void browser_window_reload(struct browser_window *bw, bool all);
+
+/**
+ * Close and destroy a browser window.
+ *
+ * \param  bw  browser window
+ */
 void browser_window_destroy(struct browser_window *bw);
+
+/**
+ * Reformat a browser window contents to a new width or height.
+ *
+ * \param  bw      the browser window to reformat
+ * \param  width   new width
+ * \param  height  new height
+ */
 void browser_window_reformat(struct browser_window *bw, bool background,
 		int width, int height);
 
@@ -294,12 +339,43 @@ bool browser_window_drop_file_at_point(struct browser_window *bw,
 void browser_window_set_gadget_filename(struct browser_window *bw,
 		struct form_control *gadget, const char *fn);
     
+/**
+ * Update URL bar for a given browser window to bw's content's URL
+ *
+ * \param bw	Browser window to update URL bar for.
+ */
 void browser_window_refresh_url_bar(struct browser_window *bw);
 
+/**
+ * Handle mouse clicks in a browser window.
+ *
+ * \param  bw	  browser window
+ * \param  mouse  state of mouse buttons and modifier keys
+ * \param  x	  coordinate of mouse
+ * \param  y	  coordinate of mouse
+ */
 void browser_window_mouse_click(struct browser_window *bw,
 		browser_mouse_state mouse, int x, int y);
+
+/**
+ * Handle non-click mouse action in a browser window. (drag ends, movements)
+ *
+ * \param  bw	  browser window
+ * \param  mouse  state of mouse buttons and modifier keys
+ * \param  x	  coordinate of mouse
+ * \param  y	  coordinate of mouse
+ */
 void browser_window_mouse_track(struct browser_window *bw,
 		browser_mouse_state mouse, int x, int y);
+
+/**
+ * Locate a browser window in the specified stack according.
+ *
+ * \param bw  the browser_window to search all relatives of
+ * \param target  the target to locate
+ * \param mouse The current mouse state
+ * \return The browser window the mouse is in
+ */
 struct browser_window *browser_window_find_target(
 		struct browser_window *bw, const char *target,
 		browser_mouse_state mouse);
@@ -322,26 +398,75 @@ nserror browser_window_schedule_reformat(struct browser_window *bw);
 void browser_select_menu_callback(void *client_data,
 		int x, int y, int width, int height);
 
+/**
+ * Redraw a rectangular region of a browser window
+ *
+ * \param  bw	  browser window to be redrawn
+ * \param  x	  x co-ord of top-left
+ * \param  y	  y co-ord of top-left
+ * \param  width  width of rectangle
+ * \param  height height of rectangle
+ */
 void browser_window_redraw_rect(struct browser_window *bw, int x, int y,
 		int width, int height);
 
+/**
+ * Change the status bar of a browser window.
+ *
+ * \param  bw	 browser window
+ * \param  text  new status text (copied)
+ */
 void browser_window_set_status(struct browser_window *bw, const char *text);
+
+/**
+ * Change the shape of the mouse pointer
+ *
+ * \param bw Browser window to set shape in
+ * \param shape The pointer shape to use
+ */
 void browser_window_set_pointer(struct browser_window *bw,
 		browser_pointer_shape shape);
+
+/**
+ * Start drag scrolling the contents of the browser window
+ *
+ * \param bw  browser window
+ * \param x   x ordinate of initial mouse position
+ * \param y   y ordinate
+ */
 void browser_window_page_drag_start(struct browser_window *bw, int x, int y);
 
+/**
+ * Check availability of Back action for a given browser window
+ *
+ * \param bw  browser window
+ * \return true if Back action is available
+ */
 bool browser_window_back_available(struct browser_window *bw);
-bool browser_window_forward_available(struct browser_window *bw);
-bool browser_window_reload_available(struct browser_window *bw);
-bool browser_window_stop_available(struct browser_window *bw);
 
+/**
+ * Check availability of Forward action for a given browser window
+ *
+ * \param bw  browser window
+ * \return true if Forward action is available
+ */
+bool browser_window_forward_available(struct browser_window *bw);
 
-/* In desktop/textinput.c */
-void browser_window_place_caret(struct browser_window *bw, int x, int y,
-		int height, const struct rect *clip);
-void browser_window_remove_caret(struct browser_window *bw, bool only_hide);
-bool browser_window_key_press(struct browser_window *bw, uint32_t key);
+/**
+ * Check availability of Reload action for a given browser window
+ *
+ * \param bw  browser window
+ * \return true if Reload action is available
+ */
+bool browser_window_reload_available(struct browser_window *bw);
 
+/**
+ * Check availability of Stop action for a given browser window
+ *
+ * \param bw  browser window
+ * \return true if Stop action is available
+ */
+bool browser_window_stop_available(struct browser_window *bw);
 
 /**
  * Redraw an area of a window
@@ -413,7 +538,7 @@ void browser_window_scroll_visible(struct browser_window *bw,
  * \param  x	    The x scroll offset to set
  * \param  y	    The y scroll offset to set
  *
- * TODO -- Do we really need this and browser_window_scroll_visible?
+ * \todo Do we really need this and browser_window_scroll_visible?
  *         Ditto for gui_window_* variants.
  */
 void browser_window_set_scroll(struct browser_window *bw, int x, int y);
diff --git a/desktop/browser_private.h b/desktop/browser_private.h
index d2c48d704..7ebdd6ebd 100644
--- a/desktop/browser_private.h
+++ b/desktop/browser_private.h
@@ -163,14 +163,32 @@ struct browser_window {
 
 
 
+/**
+ * Initialise common parts of a browser window
+ *
+ * \param flags     Flags to control operation
+ * \param bw        The window to initialise
+ * \param existing  The existing window if cloning, else NULL
+ */
 nserror browser_window_initialise_common(enum browser_window_create_flags flags,
 		struct browser_window *bw, struct browser_window *existing);
 
+/**
+ * Get the dimensions of the area a browser window occupies
+ *
+ * \param  bw      The browser window to get dimensions of
+ * \param  width   Updated to the browser window viewport width
+ * \param  height  Updated to the browser window viewport height
+ * \param  scaled  Whether we want the height with scale applied
+ */
+void browser_window_get_dimensions(struct browser_window *bw,
+		int *width, int *height, bool scaled);
+
 /**
  * Update the extent of the inside of a browser window to that of the current
  * content
  *
- * \param  bw	browser_window to update the extent of
+ * \param bw browser_window to update the extent of
  */
 void browser_window_update_extent(struct browser_window *bw);
 
diff --git a/desktop/textinput.c b/desktop/textinput.c
index 31cf9e071..bd51d5a0a 100644
--- a/desktop/textinput.c
+++ b/desktop/textinput.c
@@ -48,15 +48,7 @@
 #undef TEXTINPUT_DEBUG
 
 
-/**
- * Position the caret and assign a callback for key presses.
- *
- * \param bw		The browser window in which to place the caret
- * \param x		X coordinate of the caret
- * \param y		Y coordinate
- * \param height	Height of caret
- * \param clip		Clip rectangle for caret, or NULL if none
- */
+/* exported interface documented in desktop/textinput.h */
 void browser_window_place_caret(struct browser_window *bw, int x, int y,
 		int height, const struct rect *clip)
 {
@@ -82,7 +74,7 @@ void browser_window_place_caret(struct browser_window *bw, int x, int y,
 		crp = &cr;
 	}
 
-	/* TODO: intersect with bw viewport */
+	/** \todo intersect with bw viewport */
 
 	guit->window->place_caret(root_bw->window, x, y, height * bw->scale, crp);
 
@@ -91,12 +83,7 @@ void browser_window_place_caret(struct browser_window *bw, int x, int y,
 	root_bw->can_edit = true;
 }
 
-
-/**
- * Removes the caret and callback for key process.
- *
- * \param bw  The browser window from which to remove caret
- */
+/* exported interface documented in desktop/textinput.h */
 void browser_window_remove_caret(struct browser_window *bw, bool only_hide)
 {
 	struct browser_window *root_bw;
@@ -114,14 +101,7 @@ void browser_window_remove_caret(struct browser_window *bw, bool only_hide)
 	}
 }
 
-
-/**
- * Handle key presses in a browser window.
- *
- * \param bw   The root browser window
- * \param key  The UCS4 character codepoint
- * \return true if key handled, false otherwise
- */
+/* exported interface documented in desktop/textinput.h */
 bool browser_window_key_press(struct browser_window *bw, uint32_t key)
 {
 	struct browser_window *focus = bw->focus;
diff --git a/desktop/textinput.h b/desktop/textinput.h
index a1ee504c4..4bf8abdb6 100644
--- a/desktop/textinput.h
+++ b/desktop/textinput.h
@@ -26,6 +26,8 @@
 #ifndef _NETSURF_DESKTOP_TEXTINPUT_H_
 #define _NETSURF_DESKTOP_TEXTINPUT_H_
 
+struct browser_window;
+
 enum input_key {
 
 	KEY_SELECT_ALL = 1,
@@ -69,4 +71,32 @@ enum input_key {
 };
 
 
+/**
+ * Position the caret and assign a callback for key presses.
+ *
+ * \param bw		The browser window in which to place the caret
+ * \param x		X coordinate of the caret
+ * \param y		Y coordinate
+ * \param height	Height of caret
+ * \param clip		Clip rectangle for caret, or NULL if none
+ */
+void browser_window_place_caret(struct browser_window *bw, int x, int y,
+		int height, const struct rect *clip);
+
+/**
+ * Removes the caret and callback for key process.
+ *
+ * \param bw  The browser window from which to remove caret
+ */
+void browser_window_remove_caret(struct browser_window *bw, bool only_hide);
+
+/**
+ * Handle key presses in a browser window.
+ *
+ * \param bw   The root browser window
+ * \param key  The UCS4 character codepoint
+ * \return true if key handled, false otherwise
+ */
+bool browser_window_key_press(struct browser_window *bw, uint32_t key);
+
 #endif
-- 
cgit v1.2.3