fix remaining doccomment errors

This commit is contained in:
Vincent Sanders 2017-02-22 08:30:58 +00:00
parent d35f61caa3
commit 1820bb7e63
5 changed files with 222 additions and 54 deletions

View File

@ -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) {

View File

@ -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);

View File

@ -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);
}

View File

@ -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)

View File

@ -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);
}