From 1e41a2f1902880858b93cdef559610a321247690 Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Sun, 8 Mar 2020 04:21:32 +0700 Subject: [PATCH] Improve markup in html5 API docs. (#10655) --- site/source/docs/api_reference/html5.h.rst | 87 +++++++++++----------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/site/source/docs/api_reference/html5.h.rst b/site/source/docs/api_reference/html5.h.rst index 7edb26822094..e4a93fa5b98c 100644 --- a/site/source/docs/api_reference/html5.h.rst +++ b/site/source/docs/api_reference/html5.h.rst @@ -2209,34 +2209,34 @@ Animation and Timing ==================== The API provided here are low-level functions that directly call the relevant Web APIs and nothing more. They don't integrate with the emscripten runtime, such as checking if the program has halted and cancelling a callback if so. For that purpose, -see the function ``emscripten_set_main_loop()``. +see the function :c:func:`emscripten_set_main_loop()`. Functions --------- .. c:function:: long emscripten_set_timeout(void (*cb)(void *userData), double msecs, void *userData) - Performs a setTimeout() callback call on the given function on the calling thread. + Performs a ``setTimeout()`` callback call on the given function on the calling thread. :param cb: The callback function to call. :param msecs: Millisecond delay until the callback should fire. :param userData: Specifies a pointer sized field of custom data that will be passed in to the callback function. - :returns: An ID to the setTimeout() call that can be passed to emscripten_clear_timeout() to cancel the pending timeout timer. + :returns: An ID to the ``setTimeout()`` call that can be passed to :c:func:`emscripten_clear_timeout()` to cancel the pending timeout timer. .. c:function:: void emscripten_clear_timeout(long setTimeoutId) - Cancels a pending setTimeout() call on the calling thread. This function must be called on the same - thread as the emscripten_set_timeout() call that registered the callback. + Cancels a pending ``setTimeout()`` call on the calling thread. This function must be called on the same + thread as the :c:func:`emscripten_set_timeout()` call that registered the callback. - :param setTimeoutId: An ID returned by function emscripten_set_timeout(). + :param setTimeoutId: An ID returned by function :c:func:`emscripten_set_timeout()`. .. c:function:: void emscripten_set_timeout_loop(EM_BOOL (*cb)(double time, void *userData), double intervalMsecs, void *userData) - Initializes a setTimeout() loop on the given function on the calling thread. The specified callback - function 'cb' needs to keep returning EM_TRUE as long as the animation loop should continue to run. - When the function returns false, the setTimeout() loop will stop. + Initializes a ``setTimeout()`` loop on the given function on the calling thread. The specified callback + function 'cb' needs to keep returning ``EM_TRUE`` as long as the animation loop should continue to run. + When the function returns false, the ``setTimeout()`` loop will stop. Note: The loop will start immediately with a 0 msecs delay - the passed in intervalMsecs time specifies the interval that the consecutive callback calls should fire at. @@ -2247,61 +2247,62 @@ Functions .. c:function:: long emscripten_request_animation_frame(EM_BOOL (*cb)(double time, void *userData), void *userData) - Performs a single requestAnimationFrame() callback call on the given function on the calling thread. + Performs a single ``requestAnimationFrame()`` callback call on the given function on the calling thread. :param cb: The callback function to call. This function will receive the current high precision timer value - (value of performance.now()) at the time of the call. + (value of ``performance.now()``) at the time of the call. :param userData: Specifies a pointer sized field of custom data that will be passed in to the callback function. - :returns: An ID to the requestAnimationFrame() call that can be passed to emscripten_cancel_animation_frame() to - cancel the pending requestAnimationFrame timer. + :returns: An ID to the ``requestAnimationFrame()`` call that can be passed to + :c:func:`emscripten_cancel_animation_frame()` to + cancel the pending ``requestAnimationFrame`` timer. .. c:function:: void emscripten_cancel_animation_frame(long requestAnimationFrameId) - Cancels a registered requestAnimationFrame() callback on the calling thread before it is run. This - function must be called on the same thread as the emscripten_request_animation_frame() call that + Cancels a registered ``requestAnimationFrame()`` callback on the calling thread before it is run. This + function must be called on the same thread as the :c:func:`emscripten_request_animation_frame()` call that registered the callback. - :param requestAnimationFrameId: An ID returned by function emscripten_request_animation_frame(). + :param requestAnimationFrameId: An ID returned by function :c:func:`emscripten_request_animation_frame()`. .. c:function:: void emscripten_request_animation_frame_loop(EM_BOOL (*cb)(double time, void *userData), void *userData) - Initializes a requestAnimationFrame() loop on the given function on the calling thread. The specified - callback function 'cb' needs to keep returning EM_TRUE as long as the animation loop should continue + Initializes a ``requestAnimationFrame()`` loop on the given function on the calling thread. The specified + callback function 'cb' needs to keep returning ``EM_TRUE`` as long as the animation loop should continue to run. When the function returns false, the animation frame loop will stop. :param cb: The callback function to call. This function will receive the current high precision timer value - (value of performance.now()) at the time of the call. + (value of ``performance.now()``) at the time of the call. :param userData: Specifies a pointer sized field of custom data that will be passed in to the callback function. .. c:function:: long emscripten_set_immediate(void (*cb)(void *userData), void *userData) - Performs a setImmediate() callback call on the given function on the calling thread. Returns an ID - to the setImmediate() call that can be passed to emscripten_clear_immediate() function to cancel - a pending setImmediate() invocation. - TODO: Currently the polyfill of setImmediate() only works in the main browser thread, but not in pthreads. + Performs a ``setImmediate()`` callback call on the given function on the calling thread. Returns an ID + to the ``setImmediate()`` call that can be passed to :c:func:`emscripten_clear_immediate()` function to cancel + a pending ``setImmediate()`` invocation. + TODO: Currently the polyfill of ``setImmediate()`` only works in the main browser thread, but not in pthreads. :param cb: The callback function to call. :param userData: Specifies a pointer sized field of custom data that will be passed in to the callback function. - :returns: An ID to the setImmediate() call that can be passed to emscripten_clear_immediate() to cancel the pending callback. + :returns: An ID to the ``setImmediate()`` call that can be passed to :c:func:`emscripten_clear_immediate()` to cancel the pending callback. .. c:function:: void emscripten_clear_immediate(long setImmediateId) - Cancels a pending setImmediate() call on the calling thread. This function must be called on the same - thread as the emscripten_set_immediate() call that registered the callback. + Cancels a pending ``setImmediate()`` call on the calling thread. This function must be called on the same + thread as the :c:func:`emscripten_set_immediate()` call that registered the callback. - :param setImmediateId: An ID returned by function emscripten_set_immediate(). + :param setImmediateId: An ID returned by function :c:func:`emscripten_set_immediate()`. .. c:function:: void emscripten_set_immediate_loop(EM_BOOL (*cb)(void *userData), void *userData) - Initializes a setImmediate() loop on the given function on the calling thread. The specified callback - function 'cb' needs to keep returning EM_TRUE as long as the loop should continue to run. - When the function returns false, the setImmediate() loop will stop. - TODO: Currently the polyfill of setImmediate() only works in the main browser thread, but not in pthreads. + Initializes a ``setImmediate()`` loop on the given function on the calling thread. The specified callback + function 'cb' needs to keep returning ``EM_TRUE`` as long as the loop should continue to run. + When the function returns false, the ``setImmediate()`` loop will stop. + TODO: Currently the polyfill of ``setImmediate()`` only works in the main browser thread, but not in pthreads. :param cb: The callback function to call. :param userData: Specifies a pointer sized field of custom data that will be passed in to the callback function. @@ -2309,10 +2310,10 @@ Functions .. c:function:: long emscripten_set_interval(void (*cb)(void *userData), double intervalMsecs, void *userData) - Initializes a setInterval() loop on the given function on the calling thread. Returns an ID to the - initialized loop. Call emscripten_clear_interval() with this ID to terminate the loop. + Initializes a ``setInterval()`` loop on the given function on the calling thread. Returns an ID to the + initialized loop. Call :c:func:`emscripten_clear_interval()` with this ID to terminate the loop. Note that this function will cause the given callback to be called repeatedly. Do not call - emscripten_set_interval() again on the same callback function from inside the callback, as that would + ``emscripten_set_interval()`` again on the same callback function from inside the callback, as that would register multiple loops to run simultaneously. :param cb: The callback function to call. @@ -2324,22 +2325,22 @@ Functions .. c:function:: void emscripten_clear_interval(long setIntervalId) - Cancels a currently executing setInterval() loop on the calling thread. This function must be called on - the same thread as the emscripten_set_interval() call that registered the callback. + Cancels a currently executing ``setInterval()`` loop on the calling thread. This function must be called on + the same thread as the :c:func:`emscripten_set_interval()` call that registered the callback. - :param setIntervalId: An ID returned by function emscripten_set_interval(). + :param setIntervalId: An ID returned by function :c:func:`emscripten_set_interval()`. .. c:function:: double emscripten_date_now(void) - Calls JavaScript Date.now() function in the current thread. + Calls JavaScript ``Date.now()`` function in the current thread. :returns: The number of msecs elapsed since the UNIX epoch. (00:00:00 Thursday, 1 January 1970) .. c:function:: double emscripten_performance_now(void) - Calls JavaScript performance.now() function in the current thread. Note that the returned value of + Calls JavaScript ``performance.now()`` function in the current thread. Note that the returned value of this function is based on different time offset depending on which thread this function is called in. That is, do not compare absolute time values returned by performance.now() across threads. (comparing relative timing values is ok). On the main thread this function returns the number of milliseconds elapsed @@ -2359,21 +2360,21 @@ Functions .. c:function:: void emscripten_console_log(const char *utf8String) - Prints a string using console.log(). + Prints a string using ``console.log()``. :param utf8String: A string encoded as UTF-8. .. c:function:: void emscripten_console_warn(const char *utf8String) - Prints a string using console.warn(). + Prints a string using ``console.warn()``. :param utf8String: A string encoded as UTF-8. .. c:function:: void emscripten_console_error(const char *utf8String) - Prints a string using console.error(). + Prints a string using ``console.error()``. :param utf8String: A string encoded as UTF-8. @@ -2400,6 +2401,6 @@ Functions This function can be useful when porting code that would enter an infinite loop. Instead of actually running an infinite loop, which is not allowed on the Web, we can set up the body of - the loop to execute asynchronously (using emscripten_set_main_loop or something else), and call + the loop to execute asynchronously (using :c:func:`emscripten_set_main_loop` or something else), and call this function to halt execution, which is important as we do not want execution to continue normally.