From 0f69965805dda51cc7b6ea8404226d5f75a3b533 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Sun, 19 Feb 2017 11:32:17 +0000 Subject: clean up some of the doxygen generation warnings --- content/fetch.c | 4 ++-- desktop/hotlist.h | 1 - desktop/scrollbar.c | 11 ++++------- frontends/amiga/bitmap.h | 3 +-- frontends/amiga/cookies.c | 4 +++- frontends/amiga/corewindow.c | 12 +++++++----- frontends/amiga/corewindow.h | 2 +- frontends/amiga/history.c | 6 +++++- frontends/amiga/hotlist.c | 5 ++++- frontends/amiga/sslcert.c | 2 +- frontends/beos/plotters.cpp | 14 +++++++------- frontends/riscos/corewindow.c | 4 +++- frontends/riscos/corewindow.h | 4 ++++ frontends/riscos/plotters.c | 10 +++++----- frontends/windows/cookies.c | 17 +++++++++++++++-- frontends/windows/global_history.c | 2 ++ frontends/windows/hotlist.c | 2 ++ frontends/windows/localhistory.c | 10 ++++++---- frontends/windows/localhistory.h | 22 ++++++++++++++++++---- frontends/windows/ssl_cert.c | 8 +++++--- frontends/windows/window.c | 7 ++++--- utils/nsoption.h | 4 ++-- 22 files changed, 101 insertions(+), 53 deletions(-) diff --git a/content/fetch.c b/content/fetch.c index a1542eb01..a69d3e4cf 100644 --- a/content/fetch.c +++ b/content/fetch.c @@ -26,8 +26,8 @@ * around the fetcher specific methods. * * Active fetches are held in the circular linked list ::fetch_ring. There may - * be at most ::option_max_fetchers_per_host active requests per Host: header. - * There may be at most ::option_max_fetchers active requests overall. Inactive + * be at most nsoption max_fetchers_per_host active requests per Host: header. + * There may be at most nsoption max_fetchers active requests overall. Inactive * fetches are stored in the ::queue_ring waiting for use. */ diff --git a/desktop/hotlist.h b/desktop/hotlist.h index c77ac92d2..ef54f6b8b 100644 --- a/desktop/hotlist.h +++ b/desktop/hotlist.h @@ -67,7 +67,6 @@ nserror hotlist_manager_init(struct core_window_callback_table *cw_t, * allowing destruction of a GUI hotlist window, without finalising the * hotlist module. * - * \param path The path to save hotlist to * \return NSERROR_OK on success, appropriate error otherwise */ nserror hotlist_manager_fini(void); diff --git a/desktop/scrollbar.c b/desktop/scrollbar.c index 3709af8b4..4f3043416 100644 --- a/desktop/scrollbar.c +++ b/desktop/scrollbar.c @@ -128,15 +128,12 @@ void scrollbar_destroy(struct scrollbar *s) /** * Draw an outline rectangle common to several scrollbar elements. * - * \param x0 left border of the outline - * \param y0 top border of the outline - * \param x1 right border of the outline - * \param y1 bottom border of the outline - * \param c base colour of the outline, the other colours are created by + * \param ctx current redraw context + * \param area the area of the scrollbar + * \param c base colour of the outline, the other colours are created by * lightening or darkening this one - * \param ctx current redraw context * \param inset true for inset outline, false for an outset one - * \return + * \return NSERROR_OK on success else error code */ static inline nserror diff --git a/frontends/amiga/bitmap.h b/frontends/amiga/bitmap.h index 17939d79a..aaec26ac2 100755 --- a/frontends/amiga/bitmap.h +++ b/frontends/amiga/bitmap.h @@ -76,8 +76,7 @@ void ami_bitmap_set_icondata(struct bitmap *bm, ULONG *icondata); /** * Free an icondata pointer * - * \param bm a bitmap, as returned by bitmap_create() - * \param icondata a pointer to memory + * \param bm a bitmap, as returned by bitmap_create() * * This function probably shouldn't be here! */ diff --git a/frontends/amiga/cookies.c b/frontends/amiga/cookies.c index 877805cda..fd71a9c2a 100644 --- a/frontends/amiga/cookies.c +++ b/frontends/amiga/cookies.c @@ -136,7 +136,7 @@ ami_cookies_mouse(struct ami_corewindow *ami_cw, /** * callback for keypress for cookies viewer on core window * - * \param example_cw The Amiga core window structure. + * \param ami_cw The Amiga core window structure. * \param nskey The netsurf key code * \return NSERROR_OK on success otherwise apropriate error code */ @@ -153,6 +153,8 @@ ami_cookies_key(struct ami_corewindow *ami_cw, uint32_t nskey) * callback on draw event for cookies viewer on core window * * \param ami_cw The Amiga core window structure. + * \param x The x cordinate to plot at + * \param y The y cordinate to plot at * \param r The rectangle of the window that needs updating. * \param ctx The drawing context * \return NSERROR_OK on success otherwise apropriate error code diff --git a/frontends/amiga/corewindow.c b/frontends/amiga/corewindow.c index 84861e073..86c21b8a1 100644 --- a/frontends/amiga/corewindow.c +++ b/frontends/amiga/corewindow.c @@ -203,15 +203,16 @@ ami_cw_key(struct ami_corewindow *ami_cw, int nskey) /** * Redraw functions * - * This is slightly over-engineered as it was taken from the main browser/old tree redraws - * and supports deferred drawing of rectangles and tiling + * This is slightly over-engineered as it was taken from the main + * browser/old tree redraws and supports deferred drawing of + * rectangles and tiling */ /** * Redraw an area of a core window * - * \param g a struct ami_corewindow - * \param r rect (in document co-ordinates) + * \param ami_cw An Amiga core window structure + * \param r rect (in document co-ordinates) */ static void @@ -302,7 +303,8 @@ ami_cw_redraw_rect(struct ami_corewindow *ami_cw, struct rect *r) /** * Draw the deferred rectangles * - * @param draw set to false to just delete the queue + * \param ami_cw An Amiga core window structure to queue redraw + * \param draw set to false to just delete the queue */ static void ami_cw_redraw_queue(struct ami_corewindow *ami_cw, bool draw) { diff --git a/frontends/amiga/corewindow.h b/frontends/amiga/corewindow.h index cc4fe4adb..ea01f67f1 100644 --- a/frontends/amiga/corewindow.h +++ b/frontends/amiga/corewindow.h @@ -171,7 +171,7 @@ struct ami_corewindow { * * As a pre-requisite the draw, key and mouse callbacks must be defined * - * \param example_cw An Amiga core window structure to initialise + * \param ami_cw An Amiga core window structure to initialise * \return NSERROR_OK on successful initialisation otherwise error code. */ nserror ami_corewindow_init(struct ami_corewindow *ami_cw); diff --git a/frontends/amiga/history.c b/frontends/amiga/history.c index 12c306a9b..7fc1ec333 100644 --- a/frontends/amiga/history.c +++ b/frontends/amiga/history.c @@ -162,12 +162,16 @@ ami_history_global_key(struct ami_corewindow *ami_cw, uint32_t nskey) * callback on draw event for history viewer on core window * * \param ami_cw The Amiga core window structure. + * \param x The x coordinate of global history area to redraw + * \param y The y coordinate of global history area to redraw * \param r The rectangle of the window that needs updating. * \param ctx The drawing context * \return NSERROR_OK on success otherwise apropriate error code */ static nserror -ami_history_global_draw(struct ami_corewindow *ami_cw, int x, int y, struct rect *r, struct redraw_context *ctx) +ami_history_global_draw(struct ami_corewindow *ami_cw, + int x, int y, struct rect *r, + struct redraw_context *ctx) { global_history_redraw(x, y, r, ctx); diff --git a/frontends/amiga/hotlist.c b/frontends/amiga/hotlist.c index 008e45a24..c0a6b6f58 100644 --- a/frontends/amiga/hotlist.c +++ b/frontends/amiga/hotlist.c @@ -213,12 +213,15 @@ ami_hotlist_key(struct ami_corewindow *ami_cw, uint32_t nskey) * callback on draw event for hotlist viewer on core window * * \param ami_cw The Amiga core window structure. + * \param x The x coordinate of hotlist area to redraw + * \param y The y coordinate of hotlist area to redraw * \param r The rectangle of the window that needs updating. * \param ctx The drawing context * \return NSERROR_OK on success otherwise apropriate error code */ static nserror -ami_hotlist_draw(struct ami_corewindow *ami_cw, int x, int y, struct rect *r, struct redraw_context *ctx) +ami_hotlist_draw(struct ami_corewindow *ami_cw, + int x, int y, struct rect *r, struct redraw_context *ctx) { hotlist_redraw(x, y, r, ctx); diff --git a/frontends/amiga/sslcert.c b/frontends/amiga/sslcert.c index 47126a011..eeb34108a 100644 --- a/frontends/amiga/sslcert.c +++ b/frontends/amiga/sslcert.c @@ -172,7 +172,7 @@ ami_crtvrfy_mouse(struct ami_corewindow *ami_cw, /** * callback for keypress for certificate verify on core window * - * \param example_cw The Amiga core window structure. + * \param ami_cw The Amiga core window structure. * \param nskey The netsurf key code * \return NSERROR_OK on success otherwise apropriate error code */ diff --git a/frontends/beos/plotters.cpp b/frontends/beos/plotters.cpp index 83a470d97..c77e6353e 100644 --- a/frontends/beos/plotters.cpp +++ b/frontends/beos/plotters.cpp @@ -20,7 +20,7 @@ /** * \file - * Target independent plotting (BeOS/Haiku implementation). + * BeOS/Haiku implementation target independent plotting. */ #define __STDBOOL_H__ 1 @@ -254,7 +254,7 @@ nsbeos_plot_clip(const struct redraw_context *ctx, const struct rect *ns_clip) * horizontal, in degrees. * * \param ctx The current redraw context. - * \param pstyle Style controlling the arc plot. + * \param style Style controlling the arc plot. * \param x The x coordinate of the arc. * \param y The y coordinate of the arc. * \param radius The radius of the arc. @@ -294,7 +294,7 @@ nsbeos_plot_arc(const struct redraw_context *ctx, * Plot a circle centered on (x,y), which is optionally filled. * * \param ctx The current redraw context. - * \param pstyle Style controlling the circle plot. + * \param style Style controlling the circle plot. * \param x x coordinate of circle centre. * \param y y coordinate of circle centre. * \param radius circle radius. @@ -334,7 +334,7 @@ nsbeos_plot_disc(const struct redraw_context *ctx, * centre of line width/thickness. * * \param ctx The current redraw context. - * \param pstyle Style controlling the line plot. + * \param style Style controlling the line plot. * \param line A rectangle defining the line to be drawn * \return NSERROR_OK on success else error code. */ @@ -393,8 +393,8 @@ nsbeos_plot_line(const struct redraw_context *ctx, * width and height. * * \param ctx The current redraw context. - * \param pstyle Style controlling the rectangle plot. - * \param rect A rectangle defining the line to be drawn + * \param style Style controlling the rectangle plot. + * \param nsrect A rectangle defining the line to be drawn * \return NSERROR_OK on success else error code. */ static nserror @@ -470,7 +470,7 @@ nsbeos_plot_rectangle(const struct redraw_context *ctx, * rule. * * \param ctx The current redraw context. - * \param pstyle Style controlling the polygon plot. + * \param style Style controlling the polygon plot. * \param p verticies of polygon * \param n number of verticies. * \return NSERROR_OK on success else error code. diff --git a/frontends/riscos/corewindow.c b/frontends/riscos/corewindow.c index 3219be985..89132853d 100644 --- a/frontends/riscos/corewindow.c +++ b/frontends/riscos/corewindow.c @@ -378,7 +378,7 @@ ro_cw_drag_start(struct ro_corewindow *ro_cw, * The wimp has issued an event to the window because the pointer has * entered it. * - * \param open The open event to be processed + * \param entering The entering event to be processed */ static void ro_cw_pointer_entering(wimp_entering *entering) { @@ -664,6 +664,8 @@ static void cw_tb_update(void *ctx) * Respond to user actions (click) in a corewindow. * * \param ctx Context as passed to toolbar creation. + * \param action_type type of action on toolbar + * \param action data for action. */ static void cw_tb_click(void *ctx, diff --git a/frontends/riscos/corewindow.h b/frontends/riscos/corewindow.h index b340bde35..7d808c298 100644 --- a/frontends/riscos/corewindow.h +++ b/frontends/riscos/corewindow.h @@ -123,6 +123,10 @@ struct ro_corewindow { * As a pre-requisite the draw, key and mouse callbacks must be defined * * \param ro_cw A riscos core window structure to initialise + * \param tb_buttons toolbar button bar context + * \param tb_order The order of toolbar buttons + * \param tb_style The style of toolbar buttons + * \param tb_help Thh toolbar help text * \return NSERROR_OK on successful initialisation otherwise error code. */ nserror ro_corewindow_init(struct ro_corewindow *ro_cw, const struct button_bar_buttons *tb_buttons, char *tb_order, theme_style tb_style, const char *tb_help); diff --git a/frontends/riscos/plotters.c b/frontends/riscos/plotters.c index b12d6c403..b459ba1f9 100644 --- a/frontends/riscos/plotters.c +++ b/frontends/riscos/plotters.c @@ -148,7 +148,7 @@ ro_plot_clip(const struct redraw_context *ctx, const struct rect *clip) * horizontal, in degrees. * * \param ctx The current redraw context. - * \param pstyle Style controlling the arc plot. + * \param style Style controlling the arc plot. * \param x The x coordinate of the arc. * \param y The y coordinate of the arc. * \param radius The radius of the arc. @@ -214,7 +214,7 @@ ro_plot_arc(const struct redraw_context *ctx, * Plot a circle centered on (x,y), which is optionally filled. * * \param ctx The current redraw context. - * \param pstyle Style controlling the circle plot. + * \param style Style controlling the circle plot. * \param x The x coordinate of the circle. * \param y The y coordinate of the circle. * \param radius The radius of the circle. @@ -283,7 +283,7 @@ ro_plot_disc(const struct redraw_context *ctx, * centre of line width/thickness. * * \param ctx The current redraw context. - * \param pstyle Style controlling the line plot. + * \param style Style controlling the line plot. * \param line A rectangle defining the line to be drawn * \return NSERROR_OK on success else error code. */ @@ -328,7 +328,7 @@ ro_plot_line(const struct redraw_context *ctx, * width and height. * * \param ctx The current redraw context. - * \param pstyle Style controlling the rectangle plot. + * \param style Style controlling the rectangle plot. * \param rect A rectangle defining the line to be drawn * \return NSERROR_OK on success else error code. */ @@ -414,7 +414,7 @@ ro_plot_rectangle(const struct redraw_context *ctx, * rule. * * \param ctx The current redraw context. - * \param pstyle Style controlling the polygon plot. + * \param style Style controlling the polygon plot. * \param p verticies of polygon * \param n number of verticies. * \return NSERROR_OK on success else error code. diff --git a/frontends/windows/cookies.c b/frontends/windows/cookies.c index 27949fac1..c4880fa1c 100644 --- a/frontends/windows/cookies.c +++ b/frontends/windows/cookies.c @@ -58,6 +58,7 @@ nsw32_cookie_key(struct nsw32_corewindow *nsw32_cw, uint32_t nskey) return NSERROR_NOT_IMPLEMENTED; } + /** * callback for mouse action on cookie window * @@ -69,18 +70,21 @@ nsw32_cookie_key(struct nsw32_corewindow *nsw32_cw, uint32_t nskey) */ static nserror nsw32_cookie_mouse(struct nsw32_corewindow *nsw32_cw, - browser_mouse_state mouse_state, - int x, int y) + browser_mouse_state mouse_state, + int x, int y) { cookie_manager_mouse_action(mouse_state, x, y); return NSERROR_OK; } + /** * callback on draw event for cookie window * * \param nsw32_cw The nsw32 core window structure. + * \param scrollx The horizontal scroll offset. + * \param scrolly The vertical scroll offset. * \param r The rectangle of the window that needs updating. * \return NSERROR_OK on success otherwise apropriate error code */ @@ -102,6 +106,12 @@ nsw32_cookie_draw(struct nsw32_corewindow *nsw32_cw, } +/** + * callback on close event for cookie window + * + * \param nsw32_cw The nsw32 core window structure. + * \return NSERROR_OK on success otherwise apropriate error code + */ static nserror nsw32_cookie_close(struct nsw32_corewindow *nsw32_cw) { @@ -110,9 +120,11 @@ nsw32_cookie_close(struct nsw32_corewindow *nsw32_cw) return NSERROR_OK; } + /** * Creates the window for the cookie tree. * + * \param hInstance The application instance * \return NSERROR_OK on success else appropriate error code on faliure. */ static nserror nsw32_cookie_init(HINSTANCE hInstance) @@ -169,6 +181,7 @@ nserror nsw32_cookies_present(HINSTANCE hInstance) return res; } + /* exported interface documented in windows/cookie.h */ nserror nsw32_cookies_finalise(void) { diff --git a/frontends/windows/global_history.c b/frontends/windows/global_history.c index 0ef09632d..9ebe4381b 100644 --- a/frontends/windows/global_history.c +++ b/frontends/windows/global_history.c @@ -81,6 +81,8 @@ nsw32_global_history_mouse(struct nsw32_corewindow *nsw32_cw, * callback on draw event for global_history window * * \param nsw32_cw The nsw32 core window structure. + * \param scrollx The horizontal scroll offset. + * \param scrolly The vertical scroll offset. * \param r The rectangle of the window that needs updating. * \return NSERROR_OK on success otherwise apropriate error code */ diff --git a/frontends/windows/hotlist.c b/frontends/windows/hotlist.c index c184619bf..07804fee2 100644 --- a/frontends/windows/hotlist.c +++ b/frontends/windows/hotlist.c @@ -85,6 +85,8 @@ nsw32_hotlist_mouse(struct nsw32_corewindow *nsw32_cw, * callback on draw event for hotlist window * * \param nsw32_cw The nsw32 core window structure. + * \param scrollx The horizontal scroll offset. + * \param scrolly The vertical scroll offset. * \param r The rectangle of the window that needs updating. * \return NSERROR_OK on success otherwise apropriate error code */ diff --git a/frontends/windows/localhistory.c b/frontends/windows/localhistory.c index ae3b7f521..ea913c1a2 100644 --- a/frontends/windows/localhistory.c +++ b/frontends/windows/localhistory.c @@ -108,11 +108,13 @@ nsws_localhistory_up(struct nsws_localhistory *l, struct gui_window *gw) } -void nsws_localhistory_close(struct gui_window *w) +/* exported interface documented in windows/localhistory.h */ +void nsws_localhistory_close(struct gui_window *gw) { - struct nsws_localhistory *l = gui_window_localhistory(w); - if (l != NULL) - CloseWindow(l->hwnd); + struct nsws_localhistory *lh = gui_window_localhistory(gw); + if (lh != NULL) { + CloseWindow(lh->hwnd); + } } diff --git a/frontends/windows/localhistory.h b/frontends/windows/localhistory.h index b0ad07491..eed417f28 100644 --- a/frontends/windows/localhistory.h +++ b/frontends/windows/localhistory.h @@ -16,17 +16,31 @@ * along with this program. If not, see . */ -#ifndef _NETSURF_WINDOWS_LOCALHISTORY_H_ -#define _NETSURF_WINDOWS_LOCALHISTORY_H_ +#ifndef NETSURF_WINDOWS_LOCALHISTORY_H +#define NETSURF_WINDOWS_LOCALHISTORY_H struct nsws_localhistory; -void nsws_localhistory_open(struct gui_window *gw); +/** + * Close win32 localhistory window. + * + * \param gw The win32 gui window to close local history for. + */ void nsws_localhistory_close(struct gui_window *gw); -/* creates localhistory window */ +/** + * creates localhistory window + * + * \param gw The win32 gui window to create a local history for. + */ struct nsws_localhistory *nsws_window_create_localhistory(struct gui_window *gw); +/** + * Create the win32 window class + * + * \param hinstance The application instance to create the window class under + * \return NSERROR_OK on success else error code. + */ nserror nsws_create_localhistory_class(HINSTANCE hinstance); #endif diff --git a/frontends/windows/ssl_cert.c b/frontends/windows/ssl_cert.c index 72d1d3b55..50fb7652c 100644 --- a/frontends/windows/ssl_cert.c +++ b/frontends/windows/ssl_cert.c @@ -117,6 +117,8 @@ nsw32_sslcert_viewer_mouse(struct nsw32_corewindow *nsw32_cw, * callback on draw event for hotlist window * * \param nsw32_cw The nsw32 core window structure. + * \param scrollx The horizontal scroll offset. + * \param scrolly The vertical scroll offset. * \param r The rectangle of the window that needs updating. * \return NSERROR_OK on success otherwise apropriate error code */ @@ -332,10 +334,10 @@ static nserror nsw32_crtvrfy_destroy(struct nsw32_sslcert_window *crtwin) } /** - * handle command message on main browser window + * handle command message on ssl certificate window. * - * \param hwnd The win32 window handle - * \param gw win32 gui window + * \param hwnd The win32 window handle. + * \param crtwin certificate window context. * \param notification_code notifiction code * \param identifier notification identifier * \param ctrl_window The win32 control window handle diff --git a/frontends/windows/window.c b/frontends/windows/window.c index 94dc7c10e..bb6d6232f 100644 --- a/frontends/windows/window.c +++ b/frontends/windows/window.c @@ -809,11 +809,12 @@ static void nsws_update_edit(struct gui_window *w) * * \param gw win32 frontends graphical window. * \param hwnd The win32 window handle - * \param int x The x coordinate of the event. + * \param x The x coordinate of the event. * \param y the y cooordiante of the event. + * \return true if menu displayed else false */ static bool -nsws_ctx_menu(struct gui_window *w, HWND hwnd, int x, int y) +nsws_ctx_menu(struct gui_window *gw, HWND hwnd, int x, int y) { RECT rc; /* client area of window */ POINT pt = { x, y }; /* location of mouse click */ @@ -828,7 +829,7 @@ nsws_ctx_menu(struct gui_window *w, HWND hwnd, int x, int y) if (PtInRect(&rc, pt)) { ClientToScreen(hwnd, &pt); nsws_update_edit(w); - TrackPopupMenu(GetSubMenu(w->rclick, 0), + TrackPopupMenu(GetSubMenu(gw->rclick, 0), TPM_CENTERALIGN | TPM_TOPALIGN, x, y, diff --git a/utils/nsoption.h b/utils/nsoption.h index 62c89c464..e60ebd114 100644 --- a/utils/nsoption.h +++ b/utils/nsoption.h @@ -18,10 +18,10 @@ /** * \file - * Option reading and saving (interface). + * Option reading and saving interface. * * Global options are defined in desktop/options.h - * Distinct target options are defined in /options.h + * Distinct target options are defined in ${TARGET}/options.h * * The implementation API is slightly compromised because it still has * "global" tables for both the default and current option tables. -- cgit v1.2.3