From d1f2d29e102a3c429c892c70a7125cad3add5fe0 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Mon, 10 Nov 2014 17:00:15 +0000 Subject: Doxygen cleanups and documentation additions --- content/fetch.c | 3 ++- desktop/browser.h | 15 ++++++++------- desktop/frames.h | 2 +- desktop/print.c | 3 ++- desktop/selection.c | 20 +++++++++++--------- framebuffer/fbtk.h | 9 +++++++-- gtk/font_pango.c | 6 +++--- gtk/menu.c | 3 ++- gtk/scaffolding.c | 10 ++++++---- riscos/print.c | 4 ++-- 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 . */ -/** \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 */ -- cgit v1.2.3