From 730d59776a33ba2633a4978eb0bdb0020061bfb3 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Fri, 12 Jul 2019 13:40:26 +0100 Subject: [PATCH] cleanup some javascript documentation comments --- .../handlers/javascript/duktape/Window.bnd | 55 ++++++++++++++----- content/handlers/javascript/js.h | 47 ++++++++++------ 2 files changed, 69 insertions(+), 33 deletions(-) diff --git a/content/handlers/javascript/duktape/Window.bnd b/content/handlers/javascript/duktape/Window.bnd index b2e8166a6..1a7686250 100644 --- a/content/handlers/javascript/duktape/Window.bnd +++ b/content/handlers/javascript/duktape/Window.bnd @@ -52,7 +52,9 @@ static void window_remove_callback_bits(duk_context *ctx, size_t handle) { /* ... */ } -static void window_call_callback(duk_context *ctx, size_t handle, bool clear_entry) { +static void +window_call_callback(duk_context *ctx, size_t handle, bool clear_entry) +{ NSLOG(dukky, DEEPDEBUG, "ctx=%p, handle=%"PRIsizet, ctx, handle); /* Stack is ... */ duk_push_global_object(ctx); @@ -96,21 +98,32 @@ static void window_call_callback(duk_context *ctx, size_t handle, bool clear_ent //dukky_log_stack_frame(ctx, "On leaving callback"); } -static void window_schedule_callback(void *p) { + +static void +window_schedule_callback(void *p) +{ window_schedule_t *priv = (window_schedule_t *)p; - NSLOG(dukky, DEEPDEBUG, "Entered window scheduler callback: %"PRIsizet, priv->handle); + NSLOG(dukky, DEEPDEBUG, + "Entered window scheduler callback: %"PRIsizet, priv->handle); priv->running = true; - window_call_callback(priv->ctx, priv->handle, priv->repeat_timeout == 0); + window_call_callback(priv->ctx, + priv->handle, + priv->repeat_timeout == 0); priv->running = false; if (priv->repeat_timeout > 0) { /* Reschedule */ - NSLOG(dukky, DEEPDEBUG, "Rescheduling repeating callback %"PRIsizet, priv->handle); - guit->misc->schedule(priv->repeat_timeout, window_schedule_callback, priv); + NSLOG(dukky, DEEPDEBUG, + "Rescheduling repeating callback %"PRIsizet, + priv->handle); + guit->misc->schedule(priv->repeat_timeout, + window_schedule_callback, + priv); } else { - NSLOG(dukky, DEEPDEBUG, "Removing completed callback %"PRIsizet, priv->handle); + NSLOG(dukky, DEEPDEBUG, + "Removing completed callback %"PRIsizet, priv->handle); /* Remove this from the ring */ RING_REMOVE(priv->owner->schedule_ring, priv); window_remove_callback_bits(priv->ctx, priv->handle); @@ -118,8 +131,12 @@ static void window_schedule_callback(void *p) { } } -static size_t window_alloc_new_callback(duk_context *ctx, window_private_t *window, - bool repeating, int timeout) { +static size_t +window_alloc_new_callback(duk_context *ctx, + window_private_t *window, + bool repeating, + int timeout) +{ size_t new_handle = next_handle++; window_schedule_t *sched = calloc(sizeof *sched, 1); if (sched == NULL) { @@ -168,18 +185,24 @@ static size_t window_alloc_new_callback(duk_context *ctx, window_private_t *wind return new_handle; } -static void window_remove_callback_by_handle(duk_context *ctx, - window_private_t *window, - size_t handle) { +static void +window_remove_callback_by_handle(duk_context *ctx, + window_private_t *window, + size_t handle) +{ int res; RING_ITERATE_START(window_schedule_t, window->schedule_ring, sched) { if (sched->handle == handle) { if (sched->running) { - NSLOG(dukky, DEEPDEBUG, "Cancelling in-train callback %"PRIsizet, sched->handle); + NSLOG(dukky, DEEPDEBUG, + "Cancelling in-train callback %"PRIsizet, + sched->handle); sched->repeat_timeout = 0; } else { - NSLOG(dukky, DEEPDEBUG, "Cancelled callback %"PRIsizet, sched->handle); + NSLOG(dukky, DEEPDEBUG, + "Cancelled callback %"PRIsizet, + sched->handle); res = guit->misc->schedule(-1, window_schedule_callback, sched); @@ -209,7 +232,9 @@ static duk_ret_t dukky_window_closedown_compartment(duk_context *ctx) NSLOG(dukky, DEEPDEBUG, "Closing down compartment"); while (priv->schedule_ring != NULL) { - window_remove_callback_by_handle(ctx, priv, priv->schedule_ring->handle); + window_remove_callback_by_handle(ctx, + priv, + priv->schedule_ring->handle); } return 0; diff --git a/content/handlers/javascript/js.h b/content/handlers/javascript/js.h index 31ab8f766..d5af7211a 100644 --- a/content/handlers/javascript/js.h +++ b/content/handlers/javascript/js.h @@ -20,12 +20,11 @@ * Interface to javascript engine functions. */ -#ifndef _NETSURF_JAVASCRIPT_JS_H_ -#define _NETSURF_JAVASCRIPT_JS_H_ +#ifndef NETSURF_JAVASCRIPT_JS_H_ +#define NETSURF_JAVASCRIPT_JS_H_ #include "utils/errors.h" - typedef struct jscontext jscontext; typedef struct jsobject jsobject; @@ -37,40 +36,50 @@ struct dom_node; struct dom_element; struct dom_string; -/** Initialise javascript interpreter */ +/** + * Initialise javascript interpreter + */ void js_initialise(void); -/** finalise javascript interpreter */ +/** + * finalise javascript interpreter + */ void js_finalise(void); -/** Create a new javascript context. +/** + * Create a new javascript context. * - * There is usually one context per browser context + * There is usually one context per browsing context (browser window) * - * \param timeout elapsed wallclock time (in seconds) before \a callback is called + * \param timeout elapsed wallclock time (in seconds) before \a callback is called * \param cb the callback when the runtime exceeds the timeout * \param cbctx The context to pass to the callback * \param jsctx Updated to the created JS context * \return NSERROR_OK on success, appropriate error otherwise. */ -nserror js_newcontext(int timeout, jscallback *cb, void *cbctx, - jscontext **jsctx); +nserror js_newcontext(int timeout, jscallback *cb, void *cbctx, jscontext **jsctx); -/** Destroy a previously created context */ +/** + * Destroy a previously created context + */ void js_destroycontext(jscontext *ctx); -/** Create a new javascript compartment +/** + * Create a new javascript compartment * * This is called once for a page with javascript script tags on * it. It constructs a fresh global window object. */ jsobject *js_newcompartment(jscontext *ctx, void *win_priv, void *doc_priv); -/* execute some javascript in a context */ +/** + * execute some javascript in a context + */ bool js_exec(jscontext *ctx, const uint8_t *txt, size_t txtlen, const char *name); - -/* fire an event at a dom node */ +/** + * fire an event at a dom node + */ bool js_fire_event(jscontext *ctx, const char *type, struct dom_document *doc, struct dom_node *target); bool @@ -82,7 +91,8 @@ js_dom_event_add_listener(jscontext *ctx, /*** New Events ***/ -/** Handle a new element being created. +/** + * Handle a new element being created. * * This is called once an element is inserted into the DOM document handled * by the context provided. The JS implementation must then scan the element @@ -90,7 +100,8 @@ js_dom_event_add_listener(jscontext *ctx, */ void js_handle_new_element(jscontext *ctx, struct dom_element *node); -/** Handle an event propagation finished callback. +/** + * Handle an event propagation finished callback. * * This is called once an event finishes propagating, no matter how it * finishes. The intent here is that the JS context can perform any cleanups @@ -99,4 +110,4 @@ void js_handle_new_element(jscontext *ctx, struct dom_element *node); */ void js_event_cleanup(jscontext *ctx, struct dom_event *evt); -#endif /* _NETSURF_JAVASCRIPT_JS_H_ */ +#endif /* NETSURF_JAVASCRIPT_JS_H_ */