Fix several doxygen issues

Docs/Doxyfile

@@ -659,13 +659,11 @@ INPUT                  = windows \
                          atari \
                          atari/plot \
                          gtk \
-                         gtk/dialogs \
                          css \
                          cocoa \
                          monkey \
                          render \
                          desktop \
-                         desktop/save_pdf \
                          amiga \
                          amiga/stringview \
                          content \

amiga/font_scan.c

@@ -153,7 +153,7 @@ struct ami_font_scan_window *ami_font_scan_gui_open(int32 fonts)
 /**
  * Update GUI showing font scanning progress
  *
- * \param win       pointer to a struct ami_font_scan_window
+ * \param fsw       pointer to a struct ami_font_scan_window
  * \param font      current font being scanned
  * \param font_num  font number being scanned
  * \param glyphs    number of unique glyphs found
@@ -443,10 +443,10 @@ void ami_font_scan_fini(lwc_string **glypharray)
  * Initialise the font glyph cache.
  * Reads an existing file or, if not present, generates a new cache.
  *
- * \param  filename       cache file to attempt to read
+ * \param  filename   cache file to attempt to read
- * \param  entries        number of entries in list
+ * \param  force_scan force re-creation of cache
- * \param  force_scan     force re-creation of cache
+ * \param  save       save the cache
- * \param  glypharray     an array of 0xffff lwc_string pointers
+ * \param  glypharray an array of 0xffff lwc_string pointers
  */
 void ami_font_scan_init(const char *filename, bool force_scan, bool save,
 		lwc_string **glypharray)

amiga/history_local.c

@@ -66,7 +66,6 @@ static void ami_history_scroller_hook(struct Hook *hook,Object *object,struct In
  *
  * \param  bw          browser window to open history for
  * \param  history     history to open
- * \param  at_pointer  open the window at the pointer
  */
 
 void ami_history_open(struct browser_window *bw, struct history *history)

amiga/plugin_hack.c

@@ -166,7 +166,6 @@ bool amiga_plugin_hack_redraw(struct content *c,
  * \param  bw      browser window containing the content
  * \param  page    content of type CONTENT_HTML containing c, or 0 if not an
  *                 object within a page
- * \param  box     box containing c, or 0 if not an object
  * \param  params  object parameters, or 0 if not an object
  */
 void amiga_plugin_hack_open(struct content *c, struct browser_window *bw,

atari/deskmenu.c

@@ -242,12 +242,13 @@ static void __CDECL menu_open_url(short item, short title, void *data)
 				      NULL,
 				      NULL,
 				      &bw);
-		/** \TODO Should not be accessing inside bw. */
+		/** \todo Should not be accessing inside bw. */
 		gw = bw->window;
 	}
 
-	/** \TODO Can we do this stuff in gui_window_create, which is called
+	/** \todo Can we do this stuff in gui_window_create, which is called
-	 *        in browser_window_create ? */
+	 *        in browser_window_create?
+	 */
 
 	/* Loose focus: */
 	window_set_focus(gw->root, WIDGET_NONE, NULL );

atari/file.c

@@ -47,7 +47,7 @@
  * @param[in,out] size The size of the space available if \a str not
  *                     NULL on input and if not NULL set to the total
  *                     output length on output.
- * @param[in] nemb The number of elements.
+ * @param[in] nelm The number of elements.
  * @param[in] ... The elements of the path as string pointers.
  * @return NSERROR_OK and the complete path is written to str
  *         or error code on faliure.
@@ -102,7 +102,7 @@ static nserror atari_basename(const char *path, char **str, size_t *size)
 /**
  * Create a path from a nsurl using GEMDOS file handling.
  *
- * @parm[in] url The url to encode.
+ * @param[in] url The url to encode.
  * @param[out] path_out A string containing the result path which should
  *                      be freed by the caller.
  * @return NSERROR_OK and the path is written to \a path or error code

desktop/gui_misc.h

@@ -70,7 +70,12 @@ struct gui_browser_table {
 	nserror (*launch_url)(struct nsurl *url);
 
 	/**
-	 * verify certificate
+	 * Prompt the user to verify a certificate with issuse.
+	 *
+	 * \param url The URL being verified.
+	 * \param certs The certificate to be verified
+	 * \param num The number of certificates to be verified.
+	 * \param cb Callback upon user decision.
 	 */
 	void (*cert_verify)(struct nsurl *url, const struct ssl_cert_info *certs, unsigned long num, nserror (*cb)(bool proceed, void *pw), void *cbpw);
 

desktop/hotlist.c

@@ -71,9 +71,9 @@ struct hotlist_entry {
 /**
  * Set a hotlist entry's data from the url_data.
  *
- * \param e		hotlist entry to set up
+ * \param e    hotlist entry to set up.
- * \param url_data	Data associated with entry's URL
+ * \param data Data associated with entry's URL.
- * \return NSERROR_OK on success, appropriate error otherwise
+ * \return NSERROR_OK on success, appropriate error otherwise.
  */
 static nserror hotlist_create_treeview_field_visits_data(
 		struct hotlist_entry *e, const struct url_data *data)
@@ -126,9 +126,9 @@ static nserror hotlist_create_treeview_field_visits_data(
 /**
  * Set a hotlist entry's data from the url_data.
  *
- * \param e		hotlist entry to set up
+ * \param e     hotlist entry to set up
- * \param title		Title for entry, or NULL if using title from data
+ * \param title Title for entry, or NULL if using title from data
- * \param url_data	Data associated with entry's URL
+ * \param data  Data associated with entry's URL
  * \return NSERROR_OK on success, appropriate error otherwise
  */
 static nserror hotlist_create_treeview_field_data(
@@ -320,6 +320,7 @@ static nserror hotlist_add_entry_internal(nsurl *url, const char *title,
  * \param relation	Existing node to insert as relation of, or NULL
  * \param rel		Folder's relationship to relation
  * \param folder	Updated to new hotlist folder data
+ * \param default_folder Add to teh default folder.
  * \return NSERROR_OK on success, or appropriate error otherwise
  */
 static nserror hotlist_add_folder_internal(
@@ -601,8 +602,8 @@ static nserror hotlist_load_directory_cb(dom_node *node, void *ctx);
 /**
  * Parse a directory represented as a ul.
  *
- * \param  ul		DOM node for parsed ul
+ * \param ul DOM node for parsed ul.
- * \param  directory	directory to add this directory to
+ * \param ctx The hotlist context.
  * \return NSERROR_OK on success, or appropriate error otherwise
  */
 static nserror hotlist_load_directory(dom_node *ul, hotlist_load_ctx *ctx)

desktop/hotlist.h

@@ -39,9 +39,9 @@ enum browser_mouse_state;
  *
  * This must be called before any other hotlist_* function.
  *
- * \param cw_t		Callback table for core_window containing the treeview
+ * \param cw_t Callback table for core_window containing the treeview
- * \param cw		The core_window in which the treeview is shown
+ * \param core_window_handle The handle in which the treeview is shown
- * \param path		The path to hotlist file to load
+ * \param path The path to hotlist file to load
  * \return NSERROR_OK on success, appropriate error otherwise
  */
 nserror hotlist_init(struct core_window_callback_table *cw_t,
@@ -103,14 +103,14 @@ nserror hotlist_add_entry(struct nsurl *url, const char *title, bool at_y, int y
 /**
  * Add a folder to the hotlist.
  *
- * \param url		Title for folder being added, or NULL
+ * \param title Title for folder being added, or NULL
- * \param at_y		Iff true, insert at y-offest
+ * \param at_y Iff true, insert at y-offest
- * \param y		Y-offset in px from top of hotlist.  Ignored if (!at_y).
+ * \param y Y-offset in px from top of hotlist.  Ignored if (!at_y).
  * \return NSERROR_OK on success, appropriate error otherwise
  */
 nserror hotlist_add_folder(const char *title, bool at_y, int y);
 
-/*
+/**
  * Save hotlist to file
  *
  * \param path		The path to save hotlist to

gtk/viewdata.c

@@ -17,7 +17,8 @@
  */
 
 /**
- * \file generic data viewer implementation.
+ * \file
+ * generic data viewer implementation.
  *
  * This viewer can be used for utf-8 encoded chunk of data. Thie data
  * might be page source or the debugging of dom or box trees. It will

riscos/hotlist.c

@@ -323,11 +323,12 @@ void ro_gui_hotlist_toolbar_save_buttons(char *config)
 /**
  * Prepare the hotlist menu for opening
  *
- * \param  window		The window owning the menu.
+ * \param w       The window owning the menu.
- * \param  *menu		The menu about to be opened.
+ * \param i       A wimp icon
- * \param  *pointer		Pointer to the relevant wimp event block, or
+ * \param menu    The menu about to be opened.
- *				NULL for an Adjust click.
+ * \param pointer Pointer to the relevant wimp event block, or
- * \return			true if the event was handled; else false.
+ *                      NULL for an Adjust click.
+ * \return true if the event was handled; else false.
  */
 
 bool ro_gui_hotlist_menu_prepare(wimp_w w, wimp_i i, wimp_menu *menu,

riscos/mouse.c

@@ -16,8 +16,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \file mouse.c
+/** \file
- * Mouse dragging and tracking support (implementation).
+ * Mouse dragging and tracking support implementation.
  *
  * Two different functions are provided:-
  *

riscos/save.c

@@ -405,8 +405,8 @@ void gui_drag_save_object(struct gui_window *g, hlcache_handle *c,
 /**
  * Initiates drag saving of a selection from a browser window
  *
- * \param  s  selection object
+ * \param g gui window
- * \param  g  gui window
+ * \param selection selection object
  */
 
 void gui_drag_save_selection(struct gui_window *g, const char *selection)

riscos/sslcert.c

@@ -99,15 +99,13 @@ void ro_gui_cert_postinitialise(void)
 }
 
 /**
- * Open the certificate verification dialog
+ * Prompt the user to verify a certificate with issuse.
  *
- * \param  *bw			The browser window owning the certificates.
+ * \param url The URL being verified.
- * \param  *c			The content data corresponding to the
+ * \param certs The certificate to be verified
- *				certificates.
+ * \param num The number of certificates to be verified.
- * \param  *certs		The certificate details.
+ * \param cb Callback upon user decision.
- * \param  num			The number of certificates included.
  */
-
 void gui_cert_verify(nsurl *url,
 		const struct ssl_cert_info *certs, unsigned long num,
 		nserror (*cb)(bool proceed, void *pw), void *cbpw)
@@ -290,7 +288,7 @@ void ro_gui_cert_accept(wimp_pointer *pointer)
 /**
  * Handle rejection of certificate via event callback.
  *
- * \param  w		The wimp pointer block.
+ * \param pointer The wimp pointer block.
  */
 
 void ro_gui_cert_reject(wimp_pointer *pointer)

utils/file.c

@@ -45,7 +45,7 @@
  * @param[in,out] size The size of the space available if \a str not
  *                     NULL on input and if not NULL set to the total
  *                     output length on output.
- * @param[in] nemb The number of elements.
+ * @param[in] nelm The number of elements.
  * @param[in] ... The elements of the path as string pointers.
  * @return NSERROR_OK and the complete path is written to str
  *         or error code on faliure.
@@ -100,7 +100,7 @@ static nserror posix_basename(const char *path, char **str, size_t *size)
 /**
  * Create a path from a nsurl using posix file handling.
  *
- * @parm[in] url The url to encode.
+ * @param[in] url The url to encode.
  * @param[out] path_out A string containing the result path which should
  *                      be freed by the caller.
  * @return NSERROR_OK and the path is written to \a path or error code

utils/file.h

@@ -133,7 +133,7 @@ struct gui_file_table *default_file_table;
  * @param[in,out] size The size of the space available if \a str not
  *                     NULL on input and if not NULL set to the total
  *                     output length on output.
- * @param[in] nemb The number of elements.
+ * @param[in] nelm The number of elements.
  * @param[in] ... The elements of the path as string pointers.
  * @return NSERROR_OK and the complete path is written to str
  *         or error code on faliure.
@@ -143,7 +143,7 @@ nserror netsurf_mkpath(char **str, size_t *size, size_t nelm, ...);
 /**
  * Create a path from a nsurl.
  *
- * @parm[in] url The url to encode.
+ * @param[in] url The url to encode.
  * @param[out] path_out A string containing the result path which  must be
  *                      freed by the caller.
  * @return NSERROR_OK and the path is written to \a path_out or error code on

utils/utf8.h

@@ -34,9 +34,9 @@
  * Encoding of UCS values outside the UTF-16 plane has been removed from
  * RFC3629. This function conforms to RFC2279, however.
  *
- * \param s_in  The sequence to process
+ * \param[in] s The sequence to process
- * \param l  Length of sequence
+ * \param[in] l Length of sequence
- * \return   UCS4 character
+ * \return UCS4 character
  */
 uint32_t utf8_to_ucs4(const char *s, size_t l);
 
@@ -128,6 +128,7 @@ nserror utf8_to_enc(const char *string, const char *encname,
  * \param encname The encoding name (suitable for passing to iconv)
  * \param len     Length of input string to consider (in bytes), or 0
  * \param result  Pointer to location to store result (allocated on heap)
+ * \param result_len The length of the data placed in result.
  * \return standard nserror value
  */
 nserror utf8_from_enc(const char *string, const char *encname,