From a99b1325d78afe2fecd4b676f8338b2830dfbc6c Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Wed, 12 Nov 2014 11:45:07 +0000
Subject: Doxygen cleanups

---
 gtk/theme.c            |  7 +++--
 render/box_construct.c | 11 +++----
 render/form.c          | 77 +++++++-----------------------------------------
 render/form_internal.h | 80 +++++++++++++++++++++++++++++++++++++++++++++-----
 riscos/gui/url_bar.c   |  2 +-
 riscos/url_complete.c  |  2 +-
 riscos/window.c        |  6 ++--
 riscos/window.h        |  2 +-
 8 files changed, 100 insertions(+), 87 deletions(-)

diff --git a/gtk/theme.c b/gtk/theme.c
index 809a27823..9e673da6a 100644
--- a/gtk/theme.c
+++ b/gtk/theme.c
@@ -465,8 +465,11 @@ nsgtk_theme_image_default(nsgtk_toolbar_button tbbutton, GtkIconSize iconsize)
 }
 
 /**
- * returns default image for search buttons / menu items from gtk stock items
- * \param tbbutton button reference
+ * Get default image for search buttons / menu items from gtk stock items
+ *
+ * \param tbbutton search button reference
+ * \param iconsize The size of icons to select.
+ * \return default search image.
  */
 
 static GtkImage *
diff --git a/render/box_construct.c b/render/box_construct.c
index 3d7be33e5..a5e0069b7 100644
--- a/render/box_construct.c
+++ b/render/box_construct.c
@@ -20,7 +20,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \file
+/**
+ * \file
  * Conversion of XML tree to box tree (implementation).
  */
 
@@ -1634,9 +1635,9 @@ bool box_noscript(BOX_SPECIAL_PARAMS)
 
 
 /**
- * Destructor for object_params, for <object> elements
+ * Destructor for object_params, for &lt;object&gt; elements
  *
- * \param b	The object params being destroyed.
+ * \param o  The object params being destroyed.
  * \return 0 to allow talloc to continue destroying the tree.
  */
 static int box_object_talloc_destructor(struct object_params *o)
@@ -2221,9 +2222,9 @@ bool box_create_frameset(struct content_html_frames *f, dom_node *n,
 
 
 /**
- * Destructor for content_html_iframe, for <iframe> elements
+ * Destructor for content_html_iframe, for &lt;iframe&gt; elements
  *
- * \param b	The iframe params being destroyed.
+ * \param f The iframe params being destroyed.
  * \return 0 to allow talloc to continue destroying the tree.
  */
 static int box_iframes_talloc_destructor(struct content_html_iframe *f)
diff --git a/render/form.c b/render/form.c
index 45a517dff..94cbcfcd3 100644
--- a/render/form.c
+++ b/render/form.c
@@ -146,17 +146,7 @@ struct form *form_new(void *node, const char *action, const char *target,
 }
 
 
-/**
- * Free a form, and any controls it owns.
- *
- * \param form  The form to free
- *
- * \note There may exist controls attached to box tree nodes which are not
- * associated with any form. These will leak at present. Ideally, they will
- * be cleaned up when the box tree is destroyed. As that currently happens
- * via talloc, this won't happen. These controls are distinguishable, as their
- * form field will be NULL.
- */
+/* exported interface documented in render/form_internal.h */
 void form_free(struct form *form)
 {
 	struct form_control *c, *d;
@@ -306,24 +296,7 @@ bool form_add_option(struct form_control *control, char *value, char *text,
 }
 
 
-/**
- * Identify 'successful' controls via the DOM.
- *
- * All text strings in the successful controls list will be in the charset most
- * appropriate for submission. Therefore, no utf8_to_* processing should be
- * performed upon them.
- *
- * \todo The chosen charset needs to be made available such that it can be
- * included in the submission request (e.g. in the fetch's Content-Type header)
- *
- * \param  form           form to search for successful controls
- * \param  submit_button  control used to submit the form, if any
- * \param  successful_controls  updated to point to linked list of
- *                        fetch_multipart_data, 0 if no controls
- * \return  true on success, false on memory exhaustion
- *
- * See HTML 4.01 section 17.13.2.
- */
+/* exported interface documented in render/form_internal.h */
 bool form_successful_controls_dom(struct form *_form,
 				  struct form_control *_submit_button,
 				  struct fetch_multipart_data **successful_controls)
@@ -1027,17 +1000,7 @@ char *form_encode_item(const char *item, uint32_t len, const char *charset,
 	return ret;
 }
 
-/**
- * Open a select menu for a select form control, creating it if necessary.
- *
- * \param client_data	data passed to the redraw callback
- * \param control	the select form control for which the menu is being
- * 			opened
- * \param callback	redraw callback for the select menu
- * \param bw		the browser window in which the select menu is being
- * 			opened
- * \return		false on memory exhaustion, true otherwise
- */
+/* exported interface documented in render/form_internal.h */
 bool form_open_select_menu(void *client_data,
 		struct form_control *control,
 		select_menu_redraw_callback callback,
@@ -1111,12 +1074,7 @@ bool form_open_select_menu(void *client_data,
 }
 
 
-/**
- * Destroy a select menu and free allocated memory.
- * 
- * \param control	the select form control owning the select menu being
- * 			destroyed
- */
+/* exported interface documented in render/form_internal.h */
 void form_free_select_menu(struct form_control *control)
 {
 	if (control->data.select.menu->scrollbar != NULL)
@@ -1125,17 +1083,8 @@ void form_free_select_menu(struct form_control *control)
 	control->data.select.menu = NULL;
 }
 
-/**
- * Redraw an opened select menu.
- * 
- * \param control	the select menu being redrawn
- * \param x		the X coordinate to draw the menu at
- * \param x		the Y coordinate to draw the menu at
- * \param scale		current redraw scale
- * \param clip		clipping rectangle
- * \param ctx		current redraw context
- * \return		true on success, false otherwise
- */
+
+/* exported interface documented in render/form_internal.h */
 bool form_redraw_select_menu(struct form_control *control, int x, int y,
 		float scale, const struct rect *clip,
 		const struct redraw_context *ctx)
@@ -1262,13 +1211,10 @@ bool form_redraw_select_menu(struct form_control *control, int x, int y,
  * Check whether a clipping rectangle is completely contained in the
  * select menu.
  *
- * \param control	the select menu to check the clipping rectangle for
- * \param scale		the current browser window scale
- * \param clip_x0	minimum x of clipping rectangle
- * \param clip_y0	minimum y of clipping rectangle
- * \param clip_x1	maximum x of clipping rectangle
- * \param clip_y1	maximum y of clipping rectangle
- * \return		true if inside false otherwise
+ * \param control  the select menu to check the clipping rectangle for
+ * \param scale    the current browser window scale
+ * \param clip     the clipping rectangle
+ * \return true if inside false otherwise
  */
 bool form_clip_inside_select_menu(struct form_control *control, float scale,
 		const struct rect *clip)
@@ -1607,8 +1553,7 @@ void form_select_menu_callback(void *client_data,
 /**
  * Set a radio form control and clear the others in the group.
  *
- * \param  content  content containing the form, of type CONTENT_TYPE
- * \param  radio    form control of type GADGET_RADIO
+ * \param radio form control of type GADGET_RADIO
  */
 
 void form_radio_set(struct form_control *radio)
diff --git a/render/form_internal.h b/render/form_internal.h
index e6df14b4e..7069f876e 100644
--- a/render/form_internal.h
+++ b/render/form_internal.h
@@ -64,18 +64,29 @@ typedef void(*select_menu_redraw_callback)(void *client_data,
 /**
  * Create a struct form.
  *
- * \param  node    DOM node associated with form
- * \param  action  URL to submit form to, or NULL for default
- * \param  target  Target frame of form, or NULL for default
- * \param  method  method and enctype
- * \param  charset acceptable encodings for form submission, or NULL
- * \param  doc_charset  encoding of containing document, or NULL
- * \param  html  HTML content containing form
- * \return  a new structure, or NULL on memory exhaustion
+ * \param node         DOM node associated with form
+ * \param action       URL to submit form to, or NULL for default
+ * \param target       Target frame of form, or NULL for default
+ * \param method       method and enctype
+ * \param charset      acceptable encodings for form submission, or NULL
+ * \param doc_charset  encoding of containing document, or NULL
+ * \return A new form or NULL on memory exhaustion
  */
 struct form *form_new(void *node, const char *action, const char *target,
 		form_method method, const char *charset,
 		const char *doc_charset);
+
+/**
+ * Free a form and any controls it owns.
+ *
+ * \note There may exist controls attached to box tree nodes which are not
+ * associated with any form. These will leak at present. Ideally, they will
+ * be cleaned up when the box tree is destroyed. As that currently happens
+ * via talloc, this won't happen. These controls are distinguishable, as their
+ * form field will be NULL.
+ *
+ * \param form The form to free
+ */
 void form_free(struct form *form);
 
 /**
@@ -94,20 +105,73 @@ bool form_add_option(struct form_control *control, char *value, char *text,
 bool form_successful_controls(struct form *form,
 		struct form_control *submit_button,
 		struct fetch_multipart_data **successful_controls);
+
+/**
+ * Identify 'successful' controls via the DOM.
+ *
+ * All text strings in the successful controls list will be in the charset most
+ * appropriate for submission. Therefore, no utf8_to_* processing should be
+ * performed upon them.
+ *
+ * \todo The chosen charset needs to be made available such that it can be
+ * included in the submission request (e.g. in the fetch's Content-Type header)
+ *
+ * See HTML 4.01 section 17.13.2.
+ *
+ * \param[in] _form  form to search for successful controls
+ * \param[in] _submit_button  control used to submit the form, if any
+ * \param[out] successful_controls  updated to point to linked list of
+ *                        fetch_multipart_data, 0 if no controls
+ * \return  true on success, false on memory exhaustion
+ */
 bool form_successful_controls_dom(struct form *form,
 		struct form_control *submit_button,
 		struct fetch_multipart_data **successful_controls);
 
+
+/**
+ * Open a select menu for a select form control, creating it if necessary.
+ *
+ * \param client_data  data passed to the redraw callback
+ * \param control  The select form control for which the menu is being opened
+ * \param callback  The redraw callback for the select menu
+ * \param c  The content the select menu is opening for.
+ * \return false on memory exhaustion, true otherwise
+ */
 bool form_open_select_menu(void *client_data,
 		struct form_control *control,
 		select_menu_redraw_callback redraw_callback,
   		struct content *c);
+
+
 void form_select_menu_callback(void *client_data,
 		int x, int y, int width, int height);
+
+
+/**
+ * Destroy a select menu and free allocated memory.
+ *
+ * \param control  the select form control owning the select menu being
+ *                  destroyed.
+ */
 void form_free_select_menu(struct form_control *control);
+
+
+/**
+ * Redraw an opened select menu.
+ *
+ * \param control  the select menu being redrawn
+ * \param x        the X coordinate to draw the menu at
+ * \param y        the Y coordinate to draw the menu at
+ * \param scale    current redraw scale
+ * \param clip     clipping rectangle
+ * \param ctx      current redraw context
+ * \return         true on success, false otherwise
+ */
 bool form_redraw_select_menu(struct form_control *control, int x, int y,
 		float scale, const struct rect *clip,
 		const struct redraw_context *ctx);
+
 bool form_clip_inside_select_menu(struct form_control *control, float scale,
 		const struct rect *clip);
 const char *form_select_mouse_action(struct form_control *control,
diff --git a/riscos/gui/url_bar.c b/riscos/gui/url_bar.c
index b5f6a6e14..29eddedca 100644
--- a/riscos/gui/url_bar.c
+++ b/riscos/gui/url_bar.c
@@ -855,7 +855,7 @@ bool ro_gui_url_bar_menu_select(struct url_bar *url_bar, wimp_i i,
 		if (error != NSERROR_OK) {
 			warn_user(messages_get_errorcode(error), 0);
 		} else {
-			gui_window_set_url(g, url);
+			ro_gui_window_set_url(g, url);
 
 			browser_window_navigate(g->bw,
 				url,
diff --git a/riscos/url_complete.c b/riscos/url_complete.c
index 6881de7ea..c4d689654 100644
--- a/riscos/url_complete.c
+++ b/riscos/url_complete.c
@@ -733,7 +733,7 @@ bool ro_gui_url_complete_click(wimp_pointer *pointer)
 		/* Do NOT make any attempt to use any of the global url
 		 * completion variables after this call to browser_window_navigate.
 		 * They will be invalidated by (at least):
-		 *   + gui_window_set_url
+		 *   + ro_gui_window_set_url
 		 *   + destruction of (i)frames within the current page
 		 * Any attempt to use them will probably result in a crash.
 		 */
diff --git a/riscos/window.c b/riscos/window.c
index 188a1d6e3..61d5ea8a0 100644
--- a/riscos/window.c
+++ b/riscos/window.c
@@ -1050,7 +1050,7 @@ void gui_window_set_pointer(struct gui_window *g, gui_pointer_shape shape)
 
 
 /* exported function documented in riscos/window.h */
-nserror gui_window_set_url(struct gui_window *g, nsurl *url)
+nserror ro_gui_window_set_url(struct gui_window *g, nsurl *url)
 {
 	if (g->toolbar) {
 		ro_toolbar_set_url(g->toolbar, nsurl_access(url), true, false);
@@ -3914,7 +3914,7 @@ void ro_gui_window_launch_url(struct gui_window *g, const char *url1)
 	if (error != NSERROR_OK) {
 		warn_user(messages_get_errorcode(error), 0);
 	} else {
-		gui_window_set_url(g, url);
+		ro_gui_window_set_url(g, url);
 
 		browser_window_navigate(g->bw, url,
 				NULL, BW_NAVIGATE_HISTORY,
@@ -5022,7 +5022,7 @@ static struct gui_window_table window_table = {
 	.reformat = riscos_window_reformat,
 
 	.set_title = gui_window_set_title,
-	.set_url = gui_window_set_url,
+	.set_url = ro_gui_window_set_url,
 	.set_icon = gui_window_set_icon,
 	.set_status = riscos_window_set_status,
 	.set_pointer = gui_window_set_pointer,
diff --git a/riscos/window.h b/riscos/window.h
index 8edacb359..2e6f6e9aa 100644
--- a/riscos/window.h
+++ b/riscos/window.h
@@ -40,7 +40,7 @@ bool ro_gui_window_check_menu(wimp_menu *menu);
  * \param g gui_window to update
  * \param url new url for address bar
  */
-nserror gui_window_set_url(struct gui_window *g, struct nsurl *url);
+nserror ro_gui_window_set_url(struct gui_window *g, struct nsurl *url);
 
 #endif
 
-- 
cgit v1.2.3