summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2017-02-22 08:30:58 +0000
committerVincent Sanders <vince@kyllikki.org>2017-02-22 08:30:58 +0000
commit1820bb7e637206b7d4b103d32aff364e5e5b529c (patch)
treead2b299d775861810aa26f640c4ff3c6043e20fa
parentd35f61caa3c84c50971c57a9afae0de5d43956f9 (diff)
downloadnetsurf-1820bb7e637206b7d4b103d32aff364e5e5b529c.tar.gz
netsurf-1820bb7e637206b7d4b103d32aff364e5e5b529c.tar.bz2
fix remaining doccomment errors
-rw-r--r--desktop/knockout.c39
-rw-r--r--desktop/local_history.h12
-rw-r--r--frontends/gtk/scaffolding.c215
-rw-r--r--frontends/windows/ssl_cert.c2
-rw-r--r--frontends/windows/window.c8
5 files changed, 222 insertions, 54 deletions
diff --git a/desktop/knockout.c b/desktop/knockout.c
index 3647a3a7b..ee66c17d2 100644
--- a/desktop/knockout.c
+++ b/desktop/knockout.c
@@ -381,6 +381,7 @@ static nserror knockout_plot_flush(const struct redraw_context *ctx)
/**
* Knockout a section of previous rendering
*
+ * \param ctx The current redraw context.
* \param x0 The left edge of the removal box
* \param y0 The bottom edge of the removal box
* \param x1 The right edge of the removal box
@@ -516,6 +517,7 @@ knockout_calculate(const struct redraw_context *ctx,
*
* \param ctx The current redraw context.
* \param pstyle Style controlling the rectangle plot.
+ * \param rect A rectangle defining the line to be drawn
* \return NSERROR_OK on success else error code.
*/
static nserror
@@ -575,11 +577,12 @@ knockout_plot_rectangle(const struct redraw_context *ctx,
/**
* Knockout line plotting.
*
- * plot a line from (x0,y0) to (x1,y1). Coordinates are at centre of
- * line width/thickness.
+ * plot a line from (x0,y0) to (x1,y1). Coordinates are at
+ * centre of line width/thickness.
*
* \param ctx The current redraw context.
* \param pstyle Style controlling the line plot.
+ * \param line A rectangle defining the line to be drawn
* \return NSERROR_OK on success else error code.
*/
static nserror
@@ -606,7 +609,9 @@ knockout_plot_line(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.
*/
static nserror
@@ -750,11 +755,15 @@ knockout_plot_text(const struct redraw_context *ctx,
/**
- * Plots a circle
+ * knockout circle plotting
*
* 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 x x coordinate of circle centre.
+ * \param y y coordinate of circle centre.
+ * \param radius circle radius.
* \return NSERROR_OK on success else error code.
*/
static nserror
@@ -786,6 +795,12 @@ knockout_plot_disc(const struct redraw_context *ctx,
* horizontal, in degrees.
*
* \param ctx The current redraw context.
+ * \param pstyle 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.
+ * \param angle1 The start angle of the arc.
+ * \param angle2 The finish angle of the arc.
* \return NSERROR_OK on success else error code.
*/
static nserror
@@ -828,6 +843,13 @@ knockout_plot_arc(const struct redraw_context *ctx,
* the image is to be scaled to.
*
* \param ctx The current redraw context.
+ * \param bitmap The bitmap to plot
+ * \param x The x coordinate to plot the bitmap
+ * \param y The y coordiante to plot the bitmap
+ * \param width The width of area to plot the bitmap into
+ * \param height The height of area to plot the bitmap into
+ * \param bg the background colour to alpha blend into
+ * \param flags the flags controlling the type of plot operation
* \return NSERROR_OK on success else error code.
*/
static nserror
@@ -905,6 +927,7 @@ knockout_plot_bitmap(const struct redraw_context *ctx,
* Used when plotter implements export to a vector graphics file format.
*
* \param ctx The current redraw context.
+ * \param name The name of the group being started.
* \return NSERROR_OK on success else error code.
*/
static nserror
@@ -923,6 +946,14 @@ knockout_plot_group_start(const struct redraw_context *ctx, const char *name)
}
+/**
+ * End a group of objects.
+ *
+ * Used when plotter implements export to a vector graphics file format.
+ *
+ * \param ctx The current redraw context.
+ * \return NSERROR_OK on success else error code.
+ */
static nserror knockout_plot_group_end(const struct redraw_context *ctx)
{
if (real_plot.group_end == NULL) {
diff --git a/desktop/local_history.h b/desktop/local_history.h
index a23cbd3ed..5425e700b 100644
--- a/desktop/local_history.h
+++ b/desktop/local_history.h
@@ -42,6 +42,7 @@ struct browser_window;
*
* \param cw_t Callback table for core_window containing the treeview.
* \param core_window_handle The core_window in which the treeview is shown.
+ * \param bw browser window to show history of.
* \param[out] session The created local history session context.
* \return NSERROR_OK on success and session set, appropriate error code otherwise
*/
@@ -67,8 +68,8 @@ nserror local_history_fini(struct local_history_session *session);
* Redraw the global history.
*
* \param session The local history session context.
- * \param x X coordinate to render treeview at
- * \param y Y coordinate to render treeview at
+ * \param x X coordinate to render history at
+ * \param y Y coordinate to render history at
* \param clip Current clip rectangle (wrt tree origin)
* \param ctx Current redraw context
*/
@@ -87,8 +88,8 @@ void local_history_mouse_action(struct local_history_session *session, enum brow
/**
* Key press handling.
*
- * \param key The ucs4 character codepoint
* \param session The local history session context.
+ * \param key The ucs4 character codepoint
* \return true if the keypress is dealt with, false otherwise.
*/
bool local_history_keypress(struct local_history_session *session, uint32_t key);
@@ -97,6 +98,8 @@ bool local_history_keypress(struct local_history_session *session, uint32_t key)
* Change the browser window to draw local history for.
*
* \param session The local history session context.
+ * \param bw browser window to show history of.
+ * \return NSERROR_OK or appropriate error code.
*/
nserror local_history_set(struct local_history_session *session, struct browser_window *bw);
@@ -104,6 +107,9 @@ nserror local_history_set(struct local_history_session *session, struct browser_
* get size of local history content area
*
* \param session The local history session context.
+ * \param[out] width on sucessful return the width of the localhistory content
+ * \param[out] height on sucessful return the height of the localhistory content
+ * \return NSERROR_OK or appropriate error code.
*/
nserror local_history_get_size(struct local_history_session *session, int *width, int *height);
diff --git a/frontends/gtk/scaffolding.c b/frontends/gtk/scaffolding.c
index 7593fc383..25f36c5d3 100644
--- a/frontends/gtk/scaffolding.c
+++ b/frontends/gtk/scaffolding.c
@@ -104,7 +104,7 @@ static gboolean nsgtk_on_##q##_activate(GtkButton *widget, gpointer data)
/** Core scaffolding structure. */
struct nsgtk_scaffolding {
- /** global linked list of scaffoldings for gui interface adjustments */
+ /** global linked list of scaffolding for gui interface adjustments */
struct nsgtk_scaffolding *next, *prev;
/** currently active gui browsing context */
@@ -148,7 +148,6 @@ struct nsgtk_scaffolding {
/** link popup menu */
struct nsgtk_link_menu *link_menu;
-
};
/** current scaffold for model dialogue use */
@@ -157,19 +156,30 @@ static struct nsgtk_scaffolding *scaf_current;
/** global list for interface changes */
static struct nsgtk_scaffolding *scaf_list = NULL;
-/** holds the context data for what's under the pointer, when the contextual
- * menu is opened.
+/**
+ * holds the context data for what's under the pointer, when the
+ * contextual menu is opened.
*/
static struct browser_window_features current_menu_features;
/**
- * Helper to hide popup menu entries by grouping
+ * Helper to hide popup menu entries by grouping.
+ *
+ * \param menu The popup menu to modify.
+ * \param submenu flag to indicate if submenus should be hidden.
+ * \param nav flag to indicate if navigation entries should be hidden.
+ * \param cnp flag to indicate if cut and paste entries should be hidden.
+ * \param custom flag to indicate if menu customisation is hidden.
*/
-static void popup_menu_hide(struct nsgtk_popup_menu *menu, bool submenu,
- bool nav, bool cnp, bool custom)
+static void
+popup_menu_hide(struct nsgtk_popup_menu *menu,
+ bool submenu,
+ bool nav,
+ bool cnp,
+ bool custom)
{
- if (submenu){
+ if (submenu) {
gtk_widget_hide(GTK_WIDGET(menu->file_menuitem));
gtk_widget_hide(GTK_WIDGET(menu->edit_menuitem));
gtk_widget_hide(GTK_WIDGET(menu->view_menuitem));
@@ -198,13 +208,24 @@ static void popup_menu_hide(struct nsgtk_popup_menu *menu, bool submenu,
}
+
/**
- * Helper to show popup menu entries by grouping
+ * Helper to show popup menu entries by grouping.
+ *
+ * \param menu The popup menu to modify.
+ * \param submenu flag to indicate if submenus should be visible.
+ * \param nav flag to indicate if navigation entries should be visible.
+ * \param cnp flag to indicate if cut and paste entries should be visible.
+ * \param custom flag to indicate if menu customisation is visible.
*/
-static void popup_menu_show(struct nsgtk_popup_menu *menu, bool submenu,
- bool nav, bool cnp, bool custom)
+static void
+popup_menu_show(struct nsgtk_popup_menu *menu,
+ bool submenu,
+ bool nav,
+ bool cnp,
+ bool custom)
{
- if (submenu){
+ if (submenu) {
gtk_widget_show(GTK_WIDGET(menu->file_menuitem));
gtk_widget_show(GTK_WIDGET(menu->edit_menuitem));
gtk_widget_show(GTK_WIDGET(menu->view_menuitem));
@@ -230,7 +251,6 @@ static void popup_menu_show(struct nsgtk_popup_menu *menu, bool submenu,
if (custom) {
gtk_widget_show(GTK_WIDGET(menu->customize_menuitem));
}
-
}
@@ -238,6 +258,12 @@ static void popup_menu_show(struct nsgtk_popup_menu *menu, bool submenu,
/**
* resource cleanup function for window destruction.
+ *
+ * gtk event called when window is being destroyed. Need to free any
+ * resources associated with this scaffold,
+ *
+ * \param widget the widget being destroyed
+ * \param data The context pointer passed when the connection was made.
*/
static void scaffolding_window_destroy(GtkWidget *widget, gpointer data)
{
@@ -264,11 +290,21 @@ static void scaffolding_window_destroy(GtkWidget *widget, gpointer data)
}
}
-/* signal delivered on window delete event, allowing to halt close if
- * download is in progress
+
+/**
+ * gtk event callback on window delete event.
+ *
+ * prevent window close if download is in progress
+ *
+ * \param widget The widget receiving the delete event
+ * \param event The event
+ * \param data The context pointer passed when the connection was made.
+ * \return TRUE to indicate message handled.
*/
-static gboolean scaffolding_window_delete_event(GtkWidget *widget,
- GdkEvent *event, gpointer data)
+static gboolean
+scaffolding_window_delete_event(GtkWidget *widget,
+ GdkEvent *event,
+ gpointer data)
{
struct nsgtk_scaffolding *g = data;
@@ -278,8 +314,13 @@ static gboolean scaffolding_window_delete_event(GtkWidget *widget,
return TRUE;
}
+
/**
- * Update the scaffoling button sensitivity, url bar and local history size
+ * Update the scaffolding controls
+ *
+ * The button sensitivity, url bar and local history visibility are updated
+ *
+ * \param g The scaffolding context to update
*/
static void scaffolding_update_context(struct nsgtk_scaffolding *g)
{
@@ -298,25 +339,38 @@ static void scaffolding_update_context(struct nsgtk_scaffolding *g)
nsgtk_local_history_hide();
}
+
/**
* Make the throbber run.
+ *
+ * scheduled callback to update the throbber
+ *
+ * \param p The context passed when scheduled.
*/
static void nsgtk_throb(void *p)
{
struct nsgtk_scaffolding *g = p;
- if (g->throb_frame >= (nsgtk_throbber->nframes - 1))
+ if (g->throb_frame >= (nsgtk_throbber->nframes - 1)) {
g->throb_frame = 1;
- else
+ } else {
g->throb_frame++;
+ }
- gtk_image_set_from_pixbuf(g->throbber, nsgtk_throbber->framedata[
- g->throb_frame]);
+ gtk_image_set_from_pixbuf(g->throbber,
+ nsgtk_throbber->framedata[g->throb_frame]);
nsgtk_schedule(100, nsgtk_throb, p);
}
-static guint nsgtk_scaffolding_update_edit_actions_sensitivity(
+
+/**
+ * edit the sensitivity of focused widget
+ *
+ * \param g The scaffolding context.
+ */
+static guint
+nsgtk_scaffolding_update_edit_actions_sensitivity(
struct nsgtk_scaffolding *g)
{
GtkWidget *widget = gtk_window_get_focus(g->window);
@@ -350,7 +404,13 @@ static guint nsgtk_scaffolding_update_edit_actions_sensitivity(
}
-static void nsgtk_scaffolding_enable_edit_actions_sensitivity(
+/**
+ * make edit actions sensitive
+ *
+ * \param g The scaffolding context.
+ */
+static void
+nsgtk_scaffolding_enable_edit_actions_sensitivity(
struct nsgtk_scaffolding *g)
{
@@ -363,22 +423,46 @@ static void nsgtk_scaffolding_enable_edit_actions_sensitivity(
}
/* signal handling functions for the toolbar, URL bar, and menu bar */
-static gboolean nsgtk_window_edit_menu_clicked(GtkWidget *widget,
- struct nsgtk_scaffolding *g)
+
+/**
+ * gtk event for edit menu being show
+ *
+ * \param widget The menu widget
+ * \param g scaffolding handle
+ * \return TRUE to indicate event handled
+ */
+static gboolean
+nsgtk_window_edit_menu_shown(GtkWidget *widget,
+ struct nsgtk_scaffolding *g)
{
nsgtk_scaffolding_update_edit_actions_sensitivity(g);
return TRUE;
}
-static gboolean nsgtk_window_edit_menu_hidden(GtkWidget *widget,
- struct nsgtk_scaffolding *g)
+/**
+ * gtk event handler for edit menu being hidden
+ *
+ * \param widget The menu widget
+ * \param g scaffolding handle
+ * \return TRUE to indicate event handled
+ */
+static gboolean
+nsgtk_window_edit_menu_hidden(GtkWidget *widget,
+ struct nsgtk_scaffolding *g)
{
nsgtk_scaffolding_enable_edit_actions_sensitivity(g);
return TRUE;
}
+/**
+ * gtk event handler for popup menu being hidden.
+ *
+ * \param widget The menu widget
+ * \param g scaffolding handle
+ * \return TRUE to indicate event handled
+ */
static gboolean nsgtk_window_popup_menu_hidden(GtkWidget *widget,
struct nsgtk_scaffolding *g)
{
@@ -386,6 +470,7 @@ static gboolean nsgtk_window_popup_menu_hidden(GtkWidget *widget,
return TRUE;
}
+/* exported interface documented in gtk/scaffolding.h */
gboolean nsgtk_window_url_activate_event(GtkWidget *widget, gpointer data)
{
struct nsgtk_scaffolding *g = data;
@@ -408,8 +493,14 @@ gboolean nsgtk_window_url_activate_event(GtkWidget *widget, gpointer data)
return TRUE;
}
+
/**
* update handler for URL entry widget
+ *
+ * \param widget The widget receiving the delete event
+ * \param event The event
+ * \param data The context pointer passed when the connection was made.
+ * \return TRUE to indicate signal handled.
*/
gboolean
nsgtk_window_url_changed(GtkWidget *widget,
@@ -419,11 +510,23 @@ nsgtk_window_url_changed(GtkWidget *widget,
return nsgtk_completion_update(GTK_ENTRY(widget));
}
+
/**
* Event handler for popup menu on toolbar.
+ *
+ * \param toolbar The toolbar being clicked
+ * \param x The x coordinate where the click happened
+ * \param y The x coordinate where the click happened
+ * \param button the buttons being pressed
+ * \param data The context pointer passed when the connection was made.
+ * \return TRUE to indicate event handled.
*/
-static gboolean nsgtk_window_tool_bar_clicked(GtkToolbar *toolbar,
- gint x, gint y, gint button, gpointer data)
+static gboolean
+nsgtk_window_tool_bar_clicked(GtkToolbar *toolbar,
+ gint x,
+ gint y,
+ gint button,
+ gpointer data)
{
struct nsgtk_scaffolding *g = (struct nsgtk_scaffolding *)data;
@@ -437,23 +540,40 @@ static gboolean nsgtk_window_tool_bar_clicked(GtkToolbar *toolbar,
return TRUE;
}
+
/**
* Update the menus when the number of tabs changes.
+ *
+ * \param notebook The notebook all the tabs are in
+ * \param page The newly added page container widget
+ * \param page_num The index of the newly added page
+ * \param g The scaffolding context containing the notebook
*/
-static void nsgtk_window_tabs_add(GtkNotebook *notebook,
- GtkWidget *page, guint page_num, struct nsgtk_scaffolding *g)
+static void
+nsgtk_window_tabs_add(GtkNotebook *notebook,
+ GtkWidget *page,
+ guint page_num,
+ struct nsgtk_scaffolding *g)
{
gboolean visible = gtk_notebook_get_show_tabs(g->notebook);
- g_object_set(g->menu_bar->view_submenu->tabs_menuitem, "visible", visible, NULL);
- g_object_set(g->menu_popup->view_submenu->tabs_menuitem, "visible", visible, NULL);
+ g_object_set(g->menu_bar->view_submenu->tabs_menuitem,
+ "visible", visible, NULL);
+ g_object_set(g->menu_popup->view_submenu->tabs_menuitem,
+ "visible", visible, NULL);
g->buttons[NEXTTAB_BUTTON]->sensitivity = visible;
g->buttons[PREVTAB_BUTTON]->sensitivity = visible;
g->buttons[CLOSETAB_BUTTON]->sensitivity = visible;
nsgtk_scaffolding_set_sensitivity(g);
}
+
/**
* Update the menus when the number of tabs changes.
+ *
+ * \param notebook The notebook all the tabs are in
+ * \param page The page container widget being removed
+ * \param page_num The index of the removed page
+ * \param gs The scaffolding context containing the notebook
*/
static void
nsgtk_window_tabs_remove(GtkNotebook *notebook,
@@ -462,7 +582,7 @@ nsgtk_window_tabs_remove(GtkNotebook *notebook,
struct nsgtk_scaffolding *gs)
{
/* if the scaffold is being destroyed it is not useful to
- * update the state, futher many of the widgets may have
+ * update the state, further many of the widgets may have
* already been destroyed.
*/
if (gtk_widget_in_destruction(GTK_WIDGET(gs->window)) == TRUE) {
@@ -486,6 +606,8 @@ nsgtk_window_tabs_remove(GtkNotebook *notebook,
/**
* Handle opening a file path.
+ *
+ * \param filename The filename to open.
*/
static void nsgtk_openfile_open(const char *filename)
{
@@ -549,6 +671,7 @@ MULTIHANDLER(newwindow)
return TRUE;
}
+/* exported interface documented in gtk/scaffolding.h */
nserror nsgtk_scaffolding_new_tab(struct gui_window *gw)
{
struct browser_window *bw = nsgtk_get_browser_window(gw);
@@ -618,8 +741,16 @@ MULTIHANDLER(openfile)
return TRUE;
}
-static gboolean nsgtk_filter_directory(const GtkFileFilterInfo *info,
- gpointer data)
+/**
+ * callback to determine if a path is a directory.
+ *
+ * \param info The path information
+ * \param data context pointer set to NULL
+ * \return TRUE if path is a directory else false
+ */
+static gboolean
+nsgtk_filter_directory(const GtkFileFilterInfo *info,
+ gpointer data)
{
DIR *d = opendir(info->filename);
if (d == NULL)
@@ -674,7 +805,7 @@ MULTIHANDLER(savepage)
path = gtk_file_chooser_get_filename(GTK_FILE_CHOOSER(fc));
d = opendir(path);
if (d == NULL) {
- LOG("Unable to open directory %s for complete save: %s", path, strerror(errno));
+ LOG("Unable to open directory %s for complete save: %s", path, strerror(errno));
if (errno == ENOTDIR)
nsgtk_warning("NoDirError", path);
else
@@ -724,7 +855,7 @@ MULTIHANDLER(pdf)
strncat(dirname, "/", PATH_MAX - strlen(dirname));
dirname[PATH_MAX - 1] = '\0';
- /* this way the scale used by PDF functions is synchronized with that
+ /* this way the scale used by PDF functions is synchronised with that
* used by the all-purpose print interface
*/
haru_nsfont_set_scale((float)option_export_scale / 100);
@@ -880,7 +1011,7 @@ MULTIHANDLER(print)
CONTENT_TEXTPLAIN) {
res = gtk_print_operation_run(print_op,
GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
- g->window,
+ g->window,
NULL);
}
@@ -2090,7 +2221,7 @@ struct nsgtk_scaffolding *nsgtk_new_scaffolding(struct gui_window *toplevel)
/* toolbar URL bar menu bar search bar signal handlers */
CONNECT(gs->menu_bar->edit_submenu->edit, "show",
- nsgtk_window_edit_menu_clicked, gs);
+ nsgtk_window_edit_menu_shown, gs);
CONNECT(gs->menu_bar->edit_submenu->edit, "hide",
nsgtk_window_edit_menu_hidden, gs);
@@ -2605,7 +2736,7 @@ void nsgtk_scaffolding_context_menu(struct nsgtk_scaffolding *g,
gtk_widget_show(GTK_WIDGET(g->menu_popup->paste_menuitem));
}
- /* hide customize */
+ /* hide customise */
popup_menu_hide(g->menu_popup, false, false, false, true);
}
diff --git a/frontends/windows/ssl_cert.c b/frontends/windows/ssl_cert.c
index b48d4f5ef..fac211c11 100644
--- a/frontends/windows/ssl_cert.c
+++ b/frontends/windows/ssl_cert.c
@@ -341,7 +341,7 @@ nsw32_window_ssl_cert_size(HWND hwnd, struct nsw32_sslcert_window *certwin)
/**
* Destroy a certificate viewing window
*
- * \param certwin The certificate viewer context
+ * \param crtwin The certificate viewer context
* \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror nsw32_crtvrfy_destroy(struct nsw32_sslcert_window *crtwin)
diff --git a/frontends/windows/window.c b/frontends/windows/window.c
index 173dfc802..c9022026b 100644
--- a/frontends/windows/window.c
+++ b/frontends/windows/window.c
@@ -1694,13 +1694,13 @@ win32_window_place_caret(struct gui_window *w, int x, int y,
/**
* Remove the win32 input focus from window
*
- * \param g window with caret
+ * \param gw window with caret
*/
-static void win32_window_remove_caret(struct gui_window *w)
+static void win32_window_remove_caret(struct gui_window *gw)
{
- if (w == NULL)
+ if (gw == NULL)
return;
- HideCaret(w->drawingarea);
+ HideCaret(gw->drawingarea);
}