Doxygen cleanups and documentation additions

10 files changed, 44 insertions, 31 deletions

diff --git a/content/fetch.c b/content/fetch.c
index 2c326e877..0ca90413a 100644
--- a/content/fetch.c
+++ b/content/fetch.c
@@ -18,7 +18,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \file
+/**
+ * \file
  * Implementation of fetching of data from a URL.
  *
  * The implementation is the fetch factory and the generic operations
diff --git a/desktop/browser.h b/desktop/browser.h
index b24885d4f..1d184b6f8 100644
--- a/desktop/browser.h
+++ b/desktop/browser.h
@@ -227,7 +227,7 @@ struct history * browser_window_get_history(struct browser_window *bw);
  * \param bw	  browser window
  * \param scaled  whether to apply current browser window scale
  * \param width   updated to content width extent in px
- * \param width   updated to content height extent in px
+ * \param height  updated to content height extent in px
  * \return NSERROR_OK, or appropriate error otherwise.
  */
 nserror browser_window_get_extents(struct browser_window *bw, bool scaled,
@@ -297,9 +297,10 @@ 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
+ * \param bw         The browser window to reformat.
+ * \param background Reformat in the background.
+ * \param width      new width
+ * \param height     new height
  */
 void browser_window_reformat(struct browser_window *bw, bool background,
 		int width, int height);
@@ -643,9 +644,9 @@ bool browser_window_is_frameset(struct browser_window *bw);
  * e.g. if the gui toolkit style-guide says all windows must have
  * scrollbars then this API can be ignored.
  *
- * \param bw	browser window to look at
- * \param h	Updated to indicate horizontal scrollbar type
- * \param h	Updated to indicate vertical scrollbar type
+ * \param bw  browser window to look at
+ * \param h   Updated to indicate horizontal scrollbar type
+ * \param v   Updated to indicate vertical scrollbar type
  * \return NSERROR_OK, or appropriate error otherwise
  */
 nserror browser_window_get_scrollbar_type(struct browser_window *bw,
diff --git a/desktop/frames.h b/desktop/frames.h
index bca7f2e68..02c513c22 100644
--- a/desktop/frames.h
+++ b/desktop/frames.h
@@ -30,7 +30,7 @@ struct scrollbar_msg_data;
  *
  * \param bw	  The browser window to create iframes for.
  * \param iframe  The iframes to create from.
- * \param NSERROR_OK or error code on faliure.
+ * \return NSERROR_OK or error code on faliure.
  */
 nserror browser_window_create_iframes(struct browser_window *bw,
 		struct content_html_iframe *iframe);
diff --git a/desktop/print.c b/desktop/print.c
index 9b698f707..1f77c8ba4 100644
--- a/desktop/print.c
+++ b/desktop/print.c
@@ -217,6 +217,7 @@ bool print_apply_settings(hlcache_handle *content,
  *
  * \param content The original content
  * \param printer The printer interface for the printer to be used
+ * \param settings The print settings to use.
  * \return true if successful, false otherwise
  */
 bool print_cleanup(hlcache_handle *content, const struct printer *printer,
@@ -241,7 +242,7 @@ bool print_cleanup(hlcache_handle *content, const struct printer *printer,
  *
  * \param configuration the requested configuration
  * \param filename the filename or NULL
- * \param font handling functions
+ * \param font_func font handling functions
  * \return print_settings in case if successful, NULL if unknown
  *                        configuration or lack of memory.
  */
diff --git a/desktop/selection.c b/desktop/selection.c
index 0f395a7a2..e2bd74722 100644
--- a/desktop/selection.c
+++ b/desktop/selection.c
@@ -216,9 +216,8 @@ void selection_init(struct selection *s, struct box *root)
  * Label each text box in the given box subtree with its position
  * in a textual representation of the content.
  *
- * \param  s     selection object
- * \param  node  box at root of subtree
- * \param  idx   current position within textual representation
+ * \param box The box at root of subtree
+ * \param idx current position within textual representation
  * \return updated position
  */
 
@@ -550,8 +549,9 @@ bool traverse_tree(struct box *box, unsigned start_idx, unsigned end_idx,
  * Traverse the current selection, calling the handler function (with its
  * handle) for all boxes that lie (partially) within the given range
  *
- * \param  handler  handler function to call
- * \param  handle   handle to pass
+ * \param s       The selection context.
+ * \param handler handler function to call
+ * \param handle  handle to pass
  * \return false iff traversal abandoned part-way through
  */
 
@@ -674,10 +674,11 @@ void selection_redraw(struct selection *s, unsigned start_idx, unsigned end_idx)
 /**
  * Append text to selection string.
  *
- * \param  text        text to be added
- * \param  length      length of text in bytes
- * \param  space       indicates whether a trailing space should be appended
- * \param  sel_string  string to append to, may be resized
+ * \param text text to be added
+ * \param length length of text in bytes
+ * \param space indicates whether a trailing space should be appended
+ * \param style The font style to use.
+ * \param sel_string string to append to, may be resized
  * \return true iff successful
  */
 
@@ -959,6 +960,7 @@ void selection_set_end(struct selection *s, unsigned offset)
  *
  * \param  s          the selection object
  * \param  start      byte offset of start of text
+ * \param  end        byte offset of end of text
  * \param  start_idx  receives the start index (in bytes) of the highlighted portion
  * \param  end_idx    receives the end index (in bytes)
  * \return true iff part of the given box lies within the selection
diff --git a/framebuffer/fbtk.h b/framebuffer/fbtk.h
index f64be42a0..ea5cf127b 100644
--- a/framebuffer/fbtk.h
+++ b/framebuffer/fbtk.h
@@ -291,6 +291,7 @@ bool fbtk_set_pos_and_size(fbtk_widget_t *widget, int x, int y, int width, int h
  * @param x       x-coordinate of caret top
  * @param y       y-coordinate of caret top
  * @param height  height of caret
+ * @param remove_caret callback when caret is removed.
  */
 void fbtk_set_caret(fbtk_widget_t *widget, bool set, int x, int y, int height,
 		void (*remove_caret)(fbtk_widget_t *widget));
@@ -452,14 +453,18 @@ void fbtk_reposition_vscroll(fbtk_widget_t *scrollv,
  * Create a widget which is to be handled entirely by the calling application.
  *
  * @param window The window to add the user widget to.
- * @param pw The private pointer which can be read using ::fbtk_get_pw
+ * @param x X coordinate of widget.
+ * @param y Y coordinate of widget.
+ * @param width Width of the widget
+ * @param height Height of the widget
+ * @param pw The private pointer which can be read using ::fbtk_get_userpw
  * @return new widget handle or NULL on error.
  */
 fbtk_widget_t *fbtk_create_user(fbtk_widget_t *window, int x, int y, int width, int height, void *pw);
 
 
 /**
- * Get the private context from a widget
+ * Get the user context from a widget
  *
  * @param widget The widget to get the context from.
  * @return The context or NULL.
diff --git a/gtk/font_pango.c b/gtk/font_pango.c
index c49b32b25..ee506380f 100644
--- a/gtk/font_pango.c
+++ b/gtk/font_pango.c
@@ -224,7 +224,7 @@ bool nsfont_split(const plot_font_style_t *fstyle,
  * \param  y	   y coordinate
  * \param  string  UTF-8 string to measure
  * \param  length  length of string
- * \param  style   plot style for this text
+ * \param  fstyle  plot style for this text
  * \return  true on success, false on error and error reported
  */
 
@@ -259,8 +259,8 @@ bool nsfont_paint(int x, int y, const char *string, size_t length,
 /**
  * Convert a plot style to a PangoFontDescription.
  *
- * \param  style	plot style for this text
- * \return  a new Pango font description
+ * \param fstyle plot style for this text
+ * \return A new Pango font description
  */
 
 PangoFontDescription *nsfont_style_to_description(
diff --git a/gtk/menu.c b/gtk/menu.c
index 065ee6bdf..8b684d6c6 100644
--- a/gtk/menu.c
+++ b/gtk/menu.c
@@ -275,8 +275,9 @@ static struct nsgtk_developer_submenu *nsgtk_menu_developer_submenu(
 
 /**
  * creates the file menu
+ *
  * \param group The gtk 'global' accelerator reference
- * \param parent The parent menu to attach to or NULL
+ * \return The new file menu or NULL on error
  */
 static struct nsgtk_file_menu *nsgtk_menu_file_submenu(GtkAccelGroup *group)
 {
diff --git a/gtk/scaffolding.c b/gtk/scaffolding.c
index 7e6692a3c..b204dbe28 100644
--- a/gtk/scaffolding.c
+++ b/gtk/scaffolding.c
@@ -1729,8 +1729,9 @@ static void nsgtk_attach_menu_handlers(struct nsgtk_scaffolding *g)
 /**
  * Create and connect handlers to popup menu.
  *
- * \param g scaffoliding to attach popup menu to.
- * \return menu structure on sucess or NULL on error.
+ * \param g scaffolding to attach popup menu to.
+ * \param group The accelerator group to use for the popup.
+ * \return menu structure on success or NULL on error.
  */
 static struct nsgtk_popup_menu *
 nsgtk_new_scaffolding_popup(struct nsgtk_scaffolding *g, GtkAccelGroup *group)
@@ -1767,7 +1768,8 @@ nsgtk_new_scaffolding_popup(struct nsgtk_scaffolding *g, GtkAccelGroup *group)
 /**
  * Create and connect handlers to link popup menu.
  *
- * \param g scaffoliding to attach popup menu to.
+ * \param g scaffolding to attach popup menu to.
+ * \param group The accelerator group to use for the popup.
  * \return true on success or false on error.
  */
 static struct nsgtk_link_menu *
@@ -2418,7 +2420,7 @@ nsgtk_scaffolding_set_websearch(struct nsgtk_scaffolding *g, const char *content
  * GTK UI callback when search provider details are updated.
  *
  * \param provider_name The providers name.
- * \param ico_bitmap The icon bitmap representing the provider.
+ * \param provider_bitmap The bitmap representing the provider.
  * \return NSERROR_OK on success else error code.
  */
 static nserror
diff --git a/riscos/print.c b/riscos/print.c
index 1d9ed3e43..829029eda 100644
--- a/riscos/print.c
+++ b/riscos/print.c
@@ -308,7 +308,7 @@ void print_update_sheets_shaded_state(bool on)
 /**
  * Send a message_PRINT_SAVE
  *
- * \param c content to print
+ * \param h handle to content to print.
  */
 
 void print_send_printsave(hlcache_handle *h)
@@ -799,7 +799,7 @@ error:
 /**
  * Declare fonts to the printer driver.
  *
- * \param  c  content being printed
+ * \param h handle to content being printed
  * \return 0 on success, error message on error
  */