documentation fixes and cleanups

amiga/misc.c

@@ -112,7 +112,7 @@ void die(const char *error)
 /**
  * Create a path from a nsurl using amiga 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
@@ -254,8 +254,8 @@ char *translate_escape_chars(const char *s)
  * @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] ... The elements of the path as string pointers.
+ * @param[in] nelm The number of elements.
+ * @param[in] ap The elements of the path as string pointers.
  * @return NSERROR_OK and the complete path is written to str
  *         or error code on faliure.
  */

atari/misc.c

@@ -203,12 +203,15 @@ static nserror load_icon_callback(hlcache_handle *handle,
 /**
  * utility function. Copied from NetSurf tree API.
  *
- * \param name	the name of the loaded icon, if it's not a full path the icon is
- *		looked for in the directory specified by icons_dir
+ * \param name the name of the loaded icon, if it's not a full path
+ *	       the icon is looked for in the directory specified by
+ *	       icons_dir.
+ * \param cb callback function to deal with hlcache callback.
+ * \param pw Context pointer to be passed to callback.
  * \return the icon in form of a content or NULL on failure
  */
-hlcache_handle *load_icon(const char *name, hlcache_handle_callback cb,
-						void * pw )
+hlcache_handle *
+load_icon(const char *name, hlcache_handle_callback cb,	void *pw)
 {
 	hlcache_handle *c;
 	nserror err;

atari/schedule.h

@@ -22,20 +22,23 @@
 
 /**
  * Process events up to current time.
+ *
+ * \return The number of miliseconds until the next scheduled event.
  */
 int schedule_run(void);
 
 /**
  * Schedule a callback.
  *
- * \param  tival     interval before the callback should be made in ms
- * \param  callback  callback function
- * \param  p         user parameter, passed to callback function
+ * \param ival interval before the callback should be made in miliseconds.
+ * \param callback callback function.
+ * \param p user parameter, passed to callback function.
+ * \return NSERROR_OK on success or appropriate error code.
  *
- * The callback function will be called as soon as possible after t ms have
- * passed.
+ * The callback function will be called as soon as possible after \a ival
+ * ms have passed.
  */
-nserror atari_schedule(int cs_ival, void (*callback)(void *p), void *p);
+nserror atari_schedule(int ival, void (*callback)(void *p), void *p);
 
 /**
  * LOG all current scheduled events.

framebuffer/fbtk.h

@@ -312,7 +312,8 @@ int fbtk_destroy_widget(fbtk_widget_t *widget);
 /********************************* Widgets *********************************/
 
 
-/** Create a window widget.
+/**
+ * Create a window widget.
  *
  * @param parent The parent window or the root widget for a top level window.
  * @param x The x location relative to the parent window.
@@ -323,7 +324,7 @@ int fbtk_destroy_widget(fbtk_widget_t *widget);
  *              window.
  * @param height The height of the window limited in a similar way to the
  *               /a width.
- * @param c The background colour.
+ * @param bg The background colour.
  * @return new window widget handle or NULL on error.
  */
 fbtk_widget_t *fbtk_create_window(fbtk_widget_t *parent, int x, int y, int width, int height, colour bg);

riscos/history.c

@@ -74,9 +74,8 @@ void ro_gui_history_init(void)
 /**
  * Open history window.
  *
- * \param  bw          browser window to open history for
- * \param  history     history to open
- * \param  at_pointer  open the window at the pointer
+ * \param g The riscos window to open history for.
+ * \param at_pointer open the window at the pointer.
  */
 
 void ro_gui_history_open(struct gui_window *g, bool at_pointer)

riscos/window.c

@@ -1072,13 +1072,7 @@ void gui_window_set_pointer(struct gui_window *g, gui_pointer_shape shape)
 }
 
 
-/**
- * Set the contents of a window's address bar.
- *
- * \param  g	gui_window to update
- * \param  url  new url for address bar
- */
-
+/* exported function documented in riscos/window.h */
 void gui_window_set_url(struct gui_window *g, const char *url)
 {
 	if (!g->toolbar)
@@ -3810,12 +3804,12 @@ bool ro_gui_window_check_menu(wimp_menu *menu)
  * Return boolean flags to show what RISC OS types we can sensibly convert
  * the given object into.
  *
- * \TODO -- This should probably be somewhere else but in window.c, and
+ * \todo This should probably be somewhere else but in window.c, and
  * should probably even be done in content_().
  *
- * \param *h			The object to test.
- * \param *export_draw		true on exit if a drawfile would be possible.
- * \param *export_sprite	true on exit if a sprite would be possible.
+ * \param h The object to test.
+ * \param export_draw true on exit if a drawfile would be possible.
+ * \param export_sprite true on exit if a sprite would be possible.
  * \return true if valid data is returned; else false.
  */
 
@@ -3855,10 +3849,10 @@ bool ro_gui_window_content_export_types(hlcache_handle *h,
 /**
  * Return true if a browser window can navigate upwards.
  *
- * \TODO -- This should probably be somewhere else but in window.c.
+ * \todo This should probably be somewhere else but in window.c.
  *
- * \param *bw		the browser window to test.
- * \return		true if navigation up is possible; else false.
+ * \param bw the browser window to test.
+ * \return true if navigation up is possible otherwise false.
  */
 
 bool ro_gui_window_up_available(struct browser_window *bw)
@@ -3987,7 +3981,7 @@ void ro_gui_window_prepare_objectinfo(hlcache_handle *object, const char *href)
  * Launch a new url in the given window.
  *
  * \param g gui_window to update
- * \param  url  url to be launched
+ * \param url1 url to be launched
  */
 
 void ro_gui_window_launch_url(struct gui_window *g, const char *url1)
@@ -4860,8 +4854,8 @@ void ro_gui_window_process_form_select_menu(struct gui_window *g,
 /**
  * Convert a RISC OS window handle to a gui_window.
  *
- * \param  w  RISC OS window handle
- * \return  pointer to a structure if found, 0 otherwise
+ * \param window RISC OS window handle.
+ * \return A pointer to a riscos gui window if found or NULL.
  */
 
 struct gui_window *ro_gui_window_lookup(wimp_w window)
@@ -4870,7 +4864,7 @@ struct gui_window *ro_gui_window_lookup(wimp_w window)
 	for (g = window_list; g; g = g->next)
 		if (g->window == window)
 			return g;
-	return 0;
+	return NULL;
 }
 
 

riscos/window.h

@@ -33,6 +33,12 @@ void ro_gui_window_initialise(void);
 
 bool ro_gui_window_check_menu(wimp_menu *menu);
 
+/**
+ * Set the contents of a window's address bar.
+ *
+ * \param g gui_window to update
+ * \param url new url for address bar
+ */
 void gui_window_set_url(struct gui_window *g, const char *url);
 
 #endif

utils/file.h

@@ -86,7 +86,7 @@ struct gui_file_table {
 	/**
 	 * Create a path from a nsurl.
 	 *
-	 * @parm[in] url The url to encode.
+	 * @param[in] url The url to encode.
 	 * @param[out] path A string containing the result path which
 	 *                  must be freed by the caller.
 	 * @return NSERROR_OK and the path is written to \a path

windows/findfile.c

@@ -93,7 +93,7 @@ static char *realpath(const char *path, char *resolved_path)
  *
  * Search order is: ~/.netsurf/, $NETSURFRES/ (where NETSURFRES is an
  * environment variable), then the path specified in
-  NETSURF_WINDOWS_RESPATH in the Makefile then .\res\ [windows paths]
+ * NETSURF_WINDOWS_RESPATH in the Makefile then .\res\ [windows paths]
  */
 
 char *nsws_find_resource(char *buf, const char *filename, const char *def)