From 8848f754e07264a8b358c34048d84139660291d1 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Wed, 2 Jul 2014 16:39:08 +0100 Subject: documentation fixes and cleanups --- amiga/misc.c | 6 +++--- atari/misc.c | 11 +++++++---- atari/schedule.h | 15 +++++++++------ framebuffer/fbtk.h | 5 +++-- riscos/history.c | 5 ++--- riscos/window.c | 36 +++++++++++++++--------------------- riscos/window.h | 6 ++++++ utils/file.h | 2 +- windows/findfile.c | 2 +- 9 files changed, 47 insertions(+), 41 deletions(-) diff --git a/amiga/misc.c b/amiga/misc.c index 67240006d..7d126c906 100755 --- a/amiga/misc.c +++ b/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. */ diff --git a/atari/misc.c b/atari/misc.c index e689b8249..bd3158406 100755 --- a/atari/misc.c +++ b/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; diff --git a/atari/schedule.h b/atari/schedule.h index 47d8c2ddf..05eebb2d7 100755 --- a/atari/schedule.h +++ b/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. diff --git a/framebuffer/fbtk.h b/framebuffer/fbtk.h index 220700fef..325db0e9b 100644 --- a/framebuffer/fbtk.h +++ b/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); diff --git a/riscos/history.c b/riscos/history.c index 8c096b88c..3b8b63ae1 100644 --- a/riscos/history.c +++ b/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) diff --git a/riscos/window.c b/riscos/window.c index e1eaf871d..5a3369769 100644 --- a/riscos/window.c +++ b/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,13 +3804,13 @@ 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 - * should probably even be done in content_(). + * \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. - * \return true if valid data is returned; else false. + * \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. */ bool ro_gui_window_content_export_types(hlcache_handle *h, @@ -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) @@ -3986,8 +3980,8 @@ 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 g gui_window to update + * \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; } diff --git a/riscos/window.h b/riscos/window.h index a55ce1b9f..c4daf8bb8 100644 --- a/riscos/window.h +++ b/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 diff --git a/utils/file.h b/utils/file.h index 7baf2f019..dbbab300e 100644 --- a/utils/file.h +++ b/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 diff --git a/windows/findfile.c b/windows/findfile.c index 51ce74829..aed43b0bf 100644 --- a/windows/findfile.c +++ b/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) -- cgit v1.2.3