From 9fde3502b659d3858cd1978d2c6535c57efbe924 Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Wed, 12 Nov 2014 23:27:13 +0000
Subject: doxygen cleanups in utils

---
 amiga/bitmap.c        |  1 +
 atari/bitmap.c        |  5 +++--
 framebuffer/bitmap.c  |  1 +
 gtk/bitmap.c          |  2 +-
 riscos/bitmap.c       | 24 ++++++++++++------------
 riscos/wimp.c         | 10 +++++++---
 riscos/wimp_event.c   | 31 +++++++++++++++++--------------
 utils/filename.c      |  2 +-
 utils/http/generics.c |  2 +-
 utils/idna.c          |  3 ++-
 utils/libdom.c        |  8 +++++---
 utils/libdom.h        |  2 ++
 utils/nsoption.c      |  4 +++-
 utils/nsoption.h      |  5 +++--
 utils/nsurl.h         |  4 +---
 utils/url.h           |  4 +++-
 windows/bitmap.c      |  1 +
 windows/gui.c         |  4 +++-
 18 files changed, 67 insertions(+), 46 deletions(-)

diff --git a/amiga/bitmap.c b/amiga/bitmap.c
index c59e34278..90f89e9d3 100644
--- a/amiga/bitmap.c
+++ b/amiga/bitmap.c
@@ -149,6 +149,7 @@ void bitmap_destroy(void *bitmap)
  *
  * \param  bitmap  a bitmap, as returned by bitmap_create()
  * \param  path    pathname for file
+ * \param flags flags controlling how the bitmap is saved.
  * \return true on success, false on error and error reported
  */
 
diff --git a/atari/bitmap.c b/atari/bitmap.c
index ff0d50873..3bca82e46 100755
--- a/atari/bitmap.c
+++ b/atari/bitmap.c
@@ -68,8 +68,8 @@ int init_mfdb(int bpp, int w, int h, uint32_t flags, MFDB * out )
 /**
  * Create a bitmap.
  *
- * \param  width   width of image in pixels
- * \param  height  width of image in pixels
+ * \param  w  width of image in pixels
+ * \param  h  width of image in pixels
  * \param  state   a flag word indicating the initial state
  * \return an opaque struct bitmap, or NULL on memory exhaustion
  */
@@ -284,6 +284,7 @@ void bitmap_destroy(void *bitmap)
  *
  * \param  bitmap  a bitmap, as returned by bitmap_create()
  * \param  path    pathname for file
+ * \param flags flags controlling how the bitmap is saved.
  * \return true on success, false on error and error reported
  */
 
diff --git a/framebuffer/bitmap.c b/framebuffer/bitmap.c
index c93c14b76..ca4be21f6 100644
--- a/framebuffer/bitmap.c
+++ b/framebuffer/bitmap.c
@@ -127,6 +127,7 @@ void bitmap_destroy(void *bitmap)
  *
  * \param  bitmap  a bitmap, as returned by bitmap_create()
  * \param  path    pathname for file
+ * \param flags flags controlling how the bitmap is saved.
  * \return true on success, false on error and error reported
  */
 
diff --git a/gtk/bitmap.c b/gtk/bitmap.c
index 3ae211497..a1cb8499c 100644
--- a/gtk/bitmap.c
+++ b/gtk/bitmap.c
@@ -341,7 +341,7 @@ bool bitmap_save(void *vbitmap, const char *path, unsigned flags)
 /**
  * The bitmap image has changed, so flush any persistant cache.
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  */
 void bitmap_modified(void *vbitmap) {
 	struct bitmap *gbitmap = (struct bitmap *)vbitmap;
diff --git a/riscos/bitmap.c b/riscos/bitmap.c
index abb21ea50..c843be6e2 100644
--- a/riscos/bitmap.c
+++ b/riscos/bitmap.c
@@ -58,7 +58,7 @@
  * Initialise a bitmaps sprite area.
  *
  * \param  bitmap  the bitmap to initialise
- * \param  clear   whether to clear the image ready for use
+ * \return true if bitmap initialised else false.
  */
 
 static bool bitmap_initialise(struct bitmap *bitmap)
@@ -106,7 +106,7 @@ static bool bitmap_initialise(struct bitmap *bitmap)
  *
  * \param  width   width of image in pixels
  * \param  height  width of image in pixels
- * \param  clear   whether to clear the image ready for use
+ * \param  state the state to create teh bitmap in.
  * \return an opaque struct bitmap, or NULL on memory exhaustion
  */
 
@@ -220,7 +220,7 @@ void bitmap_overlay_sprite(struct bitmap *bitmap, const osspriteop_header *s)
 /**
  * Sets whether a bitmap should be plotted opaque
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  * \param  opaque  whether the bitmap should be plotted opaque
  */
 void bitmap_set_opaque(void *vbitmap, bool opaque)
@@ -238,7 +238,7 @@ void bitmap_set_opaque(void *vbitmap, bool opaque)
 /**
  * Tests whether a bitmap has an opaque alpha channel
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  * \return whether the bitmap is opaque
  */
 bool bitmap_test_opaque(void *vbitmap)
@@ -287,7 +287,7 @@ bool bitmap_test_opaque(void *vbitmap)
 /**
  * Gets whether a bitmap should be plotted opaque
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  */
 bool bitmap_get_opaque(void *vbitmap)
 {
@@ -300,11 +300,11 @@ bool bitmap_get_opaque(void *vbitmap)
 /**
  * Return a pointer to the pixel data in a bitmap.
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
- * \return pointer to the pixel buffer
- *
  * The pixel data is packed as BITMAP_FORMAT, possibly with padding at the end
  * of rows. The width of a row in bytes is given by bitmap_get_rowstride().
+ *
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
+ * \return pointer to the pixel buffer
  */
 
 unsigned char *bitmap_get_buffer(void *vbitmap)
@@ -329,7 +329,7 @@ unsigned char *bitmap_get_buffer(void *vbitmap)
 /**
  * Find the width of a pixel row in bytes.
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  * \return width of a pixel row in the bitmap
  */
 
@@ -343,7 +343,7 @@ size_t bitmap_get_rowstride(void *vbitmap)
 /**
  * Free a bitmap.
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  */
 
 void bitmap_destroy(void *vbitmap)
@@ -364,7 +364,7 @@ void bitmap_destroy(void *vbitmap)
 /**
  * Save a bitmap in the platform's native format.
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  * \param  path	   pathname for file
  * \param  flags   modify the behaviour of the save
  * \return true on success, false on error and error reported
@@ -537,7 +537,7 @@ bool bitmap_save(void *vbitmap, const char *path, unsigned flags)
 /**
  * The bitmap image has changed, so flush any persistent cache.
  *
- * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \param  vbitmap  a bitmap, as returned by bitmap_create()
  */
 void bitmap_modified(void *vbitmap) {
 	struct bitmap *bitmap = (struct bitmap *) vbitmap;
diff --git a/riscos/wimp.c b/riscos/wimp.c
index fe730a706..db6c2dbbb 100644
--- a/riscos/wimp.c
+++ b/riscos/wimp.c
@@ -114,7 +114,10 @@ void ro_gui_wimp_cache_furniture_sizes(wimp_w w)
 /**
  * Reads a modes EIG factors.
  *
- * \param  mode  mode to read EIG factors for, or -1 for current
+ * \param[in] mode  mode to read EIG factors for, or -1 for current
+ * \param[out] xeig  The x eig value
+ * \param[out] yeig  The y eig value
+ * \return true on success else false. 
  */
 bool ro_gui_wimp_read_eig_factors(os_mode mode, int *xeig, int *yeig)
 {
@@ -955,8 +958,9 @@ bool ro_gui_wimp_get_sprite_dimensions(osspriteop_area *area, char *sprite,
 /**
  * Performs simple user redraw for a window.
  *
- * \param  user_fill	whether to fill the redraw area
- * \param  user_colour  the colour to use when filling
+ * \param redraw  wimp draw 
+ * \param user_fill  whether to fill the redraw area
+ * \param user_colour  the colour to use when filling
  */
 
 void ro_gui_user_redraw(wimp_draw *redraw, bool user_fill,
diff --git a/riscos/wimp_event.c b/riscos/wimp_event.c
index 40d704929..38f9b3d37 100644
--- a/riscos/wimp_event.c
+++ b/riscos/wimp_event.c
@@ -433,14 +433,17 @@ bool ro_gui_wimp_event_register_help_suffix(wimp_w w,
 /**
  * Get the associated help suffix.
  *
- * \param w		The window to get the suffix for
- * \return		The associated prefix, or NULL
+ * \param w  The window to get the suffix for
+ * \param i  The icon
+ * \param pos The os coordinates
+ * \param buttons The button state.
+ * \return The associated prefix, or NULL
  */
 
 const char *ro_gui_wimp_event_get_help_suffix(wimp_w w, wimp_i i,
 		os_coord *pos, wimp_mouse_state buttons)
 {
-	struct		event_window *window;
+	struct event_window *window;
 
 	window = ro_gui_wimp_event_find_window(w);
 	if (window == NULL || window->get_help_suffix == NULL)
@@ -1157,8 +1160,8 @@ bool ro_gui_wimp_event_pointer_entering_window(wimp_entering *entering)
  * Process a Menu click in a window, by checking for a registered window
  * menu and opening it if one is found.
  *
- * \param  *p		The pointer block from the mouse click event.
- * \return		true if the click was actioned; else false.
+ * \param  pointer The pointer block from the mouse click event.
+ * \return true if the click was actioned; else false.
  */
 
 bool ro_gui_wimp_event_process_window_menu_click(wimp_pointer *pointer)
@@ -1233,16 +1236,16 @@ bool ro_gui_wimp_event_prepare_menu(wimp_w w, wimp_i i, wimp_menu *menu)
 /**
  * Register a window menu to be (semi-)automatically handled.
  *
- * \param w			The window to attach the menu to.
- * \param *m			The menu to be attached.
- * \param menu_auto		true if the menu should be opened autimatically
- *				on Menu clicks with no task intervention; false
- *				to pass clicks to the window's Mouse Event
- *				handler and leave that to pass the menu click
- *				back to us for handling and menu opening.
- * \param bool_position_ibar	true if the menu should open in an iconbar
+ * \param w              The window to attach the menu to.
+ * \param m              The menu to be attached.
+ * \param menu_auto      true if the menu should be opened autimatically on
+ *                        Menu clicks with no task intervention; false to pass
+ *                        clicks to the window's Mouse Event handler and leave
+ *                        that to pass the menu click back to us for handling
+ *                        and menu opening.
+ * \param position_ibar	 true if the menu should open in an iconbar
  *				position; false to open at the pointer.
- * \return			true if the menu was registed ok; else false.
+ * \return true if the menu was registed ok; else false.
  */
 
 bool ro_gui_wimp_event_register_menu(wimp_w w, wimp_menu *m,
diff --git a/utils/filename.c b/utils/filename.c
index a89a1ab59..5efd56177 100644
--- a/utils/filename.c
+++ b/utils/filename.c
@@ -367,7 +367,7 @@ bool filename_flush_directory(const char *folder, int depth)
 /**
  * Recursively deletes the contents of a directory
  *
- * \param directory	the directory to delete
+ * \param folder the directory to delete
  * \return true on success, false otherwise
  */
 bool filename_delete_recursive(char *folder)
diff --git a/utils/http/generics.c b/utils/http/generics.c
index 129a56f69..e0798f901 100644
--- a/utils/http/generics.c
+++ b/utils/http/generics.c
@@ -43,7 +43,7 @@ void http___item_list_destroy(http__item *list)
  * \param input       Pointer to current input byte. Updated on exit.
  * \param itemparser  Pointer to function to parse list items
  * \param first       Pointer to first item, or NULL.
- * \param parameters  Pointer to location to receive on-heap parameter list.
+ * \param items  Pointer to location to receive on-heap parameter list.
  * \return NSERROR_OK on success,
  * 	   NSERROR_NOMEM on memory exhaustion,
  * 	   NSERROR_NOT_FOUND if no items could be parsed
diff --git a/utils/idna.c b/utils/idna.c
index b979e4ecf..0a492fadc 100644
--- a/utils/idna.c
+++ b/utils/idna.c
@@ -146,8 +146,9 @@ static bool idna__contexto_rule(int32_t cp)
  * Check if a CONTEXTJ codepoint has a rule defined,
  * and conforms to that rule.
  *
- * \param string	UCS-4 string
+ * \param label UCS-4 string
  * \param index	character in the string which is CONTEXTJ
+ * \param len The length of the label
  * \return true if conforming
  */
 static bool idna__contextj_rule(int32_t *label, int index, size_t len)
diff --git a/utils/libdom.c b/utils/libdom.c
index d6b26b46b..a996e98bf 100644
--- a/utils/libdom.c
+++ b/utils/libdom.c
@@ -314,9 +314,10 @@ static void ignore_dom_msg(uint32_t severity, void *ctx, const char *msg, ...)
 /**
  * Dump attribute/value for an element node
  *
- * \param node       The element node to dump attribute details for
- * \param attribute  The attribute to dump
- * \return  true on success, or false on error
+ * \param node  The element node to dump attribute details for
+ * \param f file handle to dump to.
+ * \param attribute The attribute to dump
+ * \return true on success, or false on error
  */
 static bool dump_dom_element_attribute(dom_node *node, FILE *f, const char *attribute)
 {
@@ -376,6 +377,7 @@ static bool dump_dom_element_attribute(dom_node *node, FILE *f, const char *attr
  * Print a line in a DOM structure dump for an element
  *
  * \param node   The node to dump
+ * \param f file handle to dump to.
  * \param depth  The node's depth
  * \return  true on success, or false on error
  */
diff --git a/utils/libdom.h b/utils/libdom.h
index 4f78cd2e9..becada315 100644
--- a/utils/libdom.h
+++ b/utils/libdom.h
@@ -36,6 +36,8 @@
  * depth-first walk the dom calling callback for each element
  *
  * \param root the dom node to use as the root of the tree walk
+ * \param callback The function called for each element
+ * \param ctx The context passed to teh callback.
  * \return true if all nodes were examined, false if the callback terminated
  *         the walk early.
  */
diff --git a/utils/nsoption.c b/utils/nsoption.c
index 669b26c3d..e987a4316 100644
--- a/utils/nsoption.c
+++ b/utils/nsoption.c
@@ -442,7 +442,9 @@ nsoption_output_value_text(struct nsoption_s *option,
  *
  * Allocates a new option table and copies an existing one into it.
  *
- * @param src The source table to copy
+ * \param[in] src The source table to copy
+ * \param[out] pdst The output table
+ * \return NSERROR_OK on success or appropriate error code.
  */
 static nserror
 nsoption_dup(struct nsoption_s *src, struct nsoption_s **pdst)
diff --git a/utils/nsoption.h b/utils/nsoption.h
index 134223aa5..75558f475 100644
--- a/utils/nsoption.h
+++ b/utils/nsoption.h
@@ -16,7 +16,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \file
+/**
+ * \file
  * Option reading and saving (interface).
  *
  * Global options are defined in desktop/options.h
@@ -172,7 +173,7 @@ typedef nserror(nsoption_set_default_t)(struct nsoption_s *defaults);
  *
  * @param set_default callback to allow the customisation of the default
  *                    options.
- * @param ppots pointer to update to get options table or NULL.
+ * @param popts pointer to update to get options table or NULL.
  * @param pdefs pointer to update to get default options table or NULL.
  * @return The error status
  */
diff --git a/utils/nsurl.h b/utils/nsurl.h
index ec00dede9..13f7e5f47 100644
--- a/utils/nsurl.h
+++ b/utils/nsurl.h
@@ -90,10 +90,8 @@ void nsurl_unref(nsurl *url);
  * \param url1	  First NetSurf URL
  * \param url2	  Second NetSurf URL
  * \param parts	  The URL components to be compared
- * \param match	  Returns true if url1 and url2 matched, else false
- * \return NSERROR_OK on success, appropriate error otherwise
+ * \return true on match else false
  *
- * If return value != NSERROR_OK, match will be false.
  */
 bool nsurl_compare(const nsurl *url1, const nsurl *url2, nsurl_component parts);
 
diff --git a/utils/url.h b/utils/url.h
index d6c5b917c..143a0a0fe 100644
--- a/utils/url.h
+++ b/utils/url.h
@@ -49,7 +49,9 @@ nserror url_escape(const char *unescaped, size_t toskip, bool sptoplus, const ch
 
 /**
  * Convert an escaped string to plain.
- * \param result unescaped string owned by caller must be freed with free()
+ *
+ * \param[in] str String to unescape.
+ * \param[out] result unescaped string owned by caller must be freed with free()
  * \return  NSERROR_OK on success
  */
 nserror url_unescape(const char *str, char **result);
diff --git a/windows/bitmap.c b/windows/bitmap.c
index 0f75ea823..a12fc2dc0 100644
--- a/windows/bitmap.c
+++ b/windows/bitmap.c
@@ -160,6 +160,7 @@ void bitmap_destroy(void *bitmap)
  *
  * \param  bitmap  a bitmap, as returned by bitmap_create()
  * \param  path    pathname for file
+ * \param flags flags controlling how the bitmap is saved.
  * \return true on success, false on error and error reported
  */
 
diff --git a/windows/gui.c b/windows/gui.c
index 487f59c8f..d1f20fb2e 100644
--- a/windows/gui.c
+++ b/windows/gui.c
@@ -1452,7 +1452,9 @@ static void gui_window_destroy(struct gui_window *w)
 
 /**
  * set window title
- * \param title the [url]
+ *
+ * \param w the Windows gui window.
+ * \param title to set on window
  */
 static void gui_window_set_title(struct gui_window *w, const char *title)
 {
-- 
cgit v1.2.3