Update HTML5 classref with autogenerated jsdoc.

(cherry picked from commit 6d02c860e3ad268ad9d9a0ad635c2cce5547d00d)

tutorials/platform/html5_shell_classref.rst

@@ -3,7 +3,7 @@
 HTML5 shell class reference
 ===========================
 
-Projects exported for the Web expose the ``Engine`` class to the JavaScript environment, that allows
+Projects exported for the Web expose the :js:class:`Engine` class to the JavaScript environment, that allows
 fine control over the engine's start-up process.
 
 This API is built in an asynchronous manner and requires basic understanding
@@ -19,248 +19,334 @@ see :ref:`Custom HTML page for Web export <doc_customizing_html5_shell>`.
 Static Methods
 ^^^^^^^^^^^^^^
 
-+---------+-------------------------------------------------------------------------------------------------------------------+
-| Promise | `Engine.load <#Engine.load>`__ **(** string basePath **)**                                                        |
-+---------+-------------------------------------------------------------------------------------------------------------------+
-| void    | `Engine.unload <#Engine.unload>`__ **(** **)**                                                                    |
-+---------+-------------------------------------------------------------------------------------------------------------------+
-| boolean | `Engine.isWebGLAvailable <#Engine.isWebGLAvailable>`__ **(** *[ number majorVersion=1 ]* **)**                    |
-+---------+-------------------------------------------------------------------------------------------------------------------+
-| void    | `Engine.setWebAssemblyFilenameExtension <#Engine.setWebAssemblyFilenameExtension>`__ **(** string extension **)** |
-+---------+-------------------------------------------------------------------------------------------------------------------+
-
-Instance Properties
-^^^^^^^^^^^^^^^^^^^
-
-+-----------------------+----------------------------------+
-| Emscripten ``Module`` | `engine.rtenv <#engine.rtenv>`__ |
-+-----------------------+----------------------------------+
++---------+-----------------------------------------------------------------------------------------------+
+| Promise | :js:attr:`load <Engine.load>` **(** string basePath **)**                                     |
++---------+-----------------------------------------------------------------------------------------------+
+| void    | :js:attr:`unload <Engine.unload>` **(** **)**                                                 |
++---------+-----------------------------------------------------------------------------------------------+
+| boolean | :js:attr:`isWebGLAvailable <Engine.isWebGLAvailable>` **(** *[ number majorVersion=1 ]* **)** |
++---------+-----------------------------------------------------------------------------------------------+
 
 Instance Methods
 ^^^^^^^^^^^^^^^^
 
-+---------+------------------------------------------------------------------------------------------------------+
-| Engine  | `Engine <#Engine>`__ **(** **)**                                                                     |
-+---------+------------------------------------------------------------------------------------------------------+
-| Promise | `engine.init <#engine.init>`__ **(** *[ string basePath ]* **)**                                     |
-+---------+------------------------------------------------------------------------------------------------------+
-| Promise | `engine.preloadFile <#engine.preloadFile>`__ **(** string\|ArrayBuffer file *[, string path ]* **)** |
-+---------+------------------------------------------------------------------------------------------------------+
-| Promise | `engine.start <#engine.start>`__ **(** *[ string arg1, string arg2, … ]* **)**                       |
-+---------+------------------------------------------------------------------------------------------------------+
-| Promise | `engine.startGame <#engine.startGame>`__ **(** string execName, string mainPack **)**                |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setUnloadAfterInit <#engine.setUnloadAfterInit>`__ **(** boolean enabled **)**               |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setCanvas <#engine.setCanvas>`__ **(** HTMLCanvasElement canvasElem **)**                    |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setCanvasResizedOnStart <#engine.setCanvasResizedOnStart>`__ **(** boolean enabled **)**     |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setLocale <#engine.setLocale>`__ **(** string locale **)**                                   |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setExecutableName <#engine.setExecutableName>`__ **(** string execName **)**                 |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setProgressFunc <#engine.setProgressFunc>`__ **(** function callback **)**                   |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setStdoutFunc <#engine.setStdoutFunc>`__ **(** function callback **)**                       |
-+---------+------------------------------------------------------------------------------------------------------+
-| void    | `engine.setStderrFunc <#engine.setStderrFunc>`__ **(** function callback **)**                       |
-+---------+------------------------------------------------------------------------------------------------------+
++---------+---------------------------------------------------------------------------------------------------------------+
+| Promise | :js:attr:`init <Engine.prototype.init>` **(** *[ string basePath ]* **)**                                     |
++---------+---------------------------------------------------------------------------------------------------------------+
+| Promise | :js:attr:`preloadFile <Engine.prototype.preloadFile>` **(** string\|ArrayBuffer file *[, string path ]* **)** |
++---------+---------------------------------------------------------------------------------------------------------------+
+| Promise | :js:attr:`start <Engine.prototype.start>` **(** EngineConfig override **)**                                   |
++---------+---------------------------------------------------------------------------------------------------------------+
+| Promise | :js:attr:`startGame <Engine.prototype.startGame>` **(** EngineConfig override **)**                           |
++---------+---------------------------------------------------------------------------------------------------------------+
+| void    | :js:attr:`copyToFS <Engine.prototype.copyToFS>` **(** string path, ArrayBuffer buffer **)**                   |
++---------+---------------------------------------------------------------------------------------------------------------+
+| void    | :js:attr:`requestQuit <Engine.prototype.requestQuit>` **(** **)**                                             |
++---------+---------------------------------------------------------------------------------------------------------------+
+
+.. js:class:: Engine( initConfig )
+
+   Create a new Engine instance with the given configuration.
+
+   :param EngineConfig initConfig:
+      The initial config for this instance.
+
+   **Static Methods**
+
+   .. js:function:: load( basePath )
+
+      Load the engine from the specified base path.
+
+      :param string basePath:
+         Base path of the engine to load.
+
+      :return:
+         A Promise that resolves once the engine is loaded.
+
+      :rtype: Promise
+
+   .. js:function:: unload( )
+
+      Unload the engine to free memory.
+
+      This method will be called automatically depending on the configuration. See :js:attr:`unloadAfterInit`.
+
+   .. js:function:: isWebGLAvailable( [ majorVersion=1 ] )
+
+      Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
+
+      :param number majorVersion:
+         The major WebGL version to check for.
+
+      :return:
+         If the given major version of WebGL is available.
+
+      :rtype: boolean
+
+   **Instance Methods**
+
+   .. js:function:: prototype.init( [ basePath ] )
+
+      Initialize the engine instance. Optionally, pass the base path to the engine to load it,
+      if it hasn't been loaded yet. See :js:meth:`Engine.load`.
+
+      :param string basePath:
+         Base path of the engine to load.
+
+      :return:
+         A ``Promise`` that resolves once the engine is loaded and initialized.
+
+      :rtype: Promise
+
+   .. js:function:: prototype.preloadFile( file [, path ] )
+
+      Load a file so it is available in the instance's file system once it runs. Must be called **before** starting the
+      instance.
+
+      If not provided, the ``path`` is derived from the URL of the loaded file.
+
+      :param string\|ArrayBuffer file:
+         The file to preload.
+
+         If a ``string`` the file will be loaded from that path.
+
+         If an ``ArrayBuffer`` or a view on one, the buffer will used as the content of the file.
+
+      :param string path:
+         Path by which the file will be accessible. Required, if ``file`` is not a string.
+
+      :return:
+         A Promise that resolves once the file is loaded.
+
+      :rtype: Promise
+
+   .. js:function:: prototype.start( override )
+
+      Start the engine instance using the given override configuration (if any).
+      :js:meth:`startGame <Engine.prototype.startGame>` can be used in typical cases instead.
+
+      This will initialize the instance if it is not initialized. For manual initialization, see :js:meth:`init <Engine.prototype.init>`.
+      The engine must be loaded beforehand.
+
+      Fails if a canvas cannot be found on the page, or not specified in the configuration.
+
+      :param EngineConfig override:
+         An optional configuration override.
+
+      :return:
+         Promise that resolves once the engine started.
+
+      :rtype: Promise
+
+   .. js:function:: prototype.startGame( override )
+
+      Start the game instance using the given configuration override (if any).
+
+      This will initialize the instance if it is not initialized. For manual initialization, see :js:meth:`init <Engine.prototype.init>`.
+
+      This will load the engine if it is not loaded, and preload the main pck.
+
+      This method expects the initial config (or the override) to have both the :js:attr:`executable` and :js:attr:`mainPack`
+      properties set (normally done by the editor during export).
+
+      :param EngineConfig override:
+         An optional configuration override.
+
+      :return:
+         Promise that resolves once the game started.
+
+      :rtype: Promise
+
+   .. js:function:: prototype.copyToFS( path, buffer )
+
+      Create a file at the specified ``path`` with the passed as ``buffer`` in the instance's file system.
+
+      :param string path:
+         The location where the file will be created.
 
+      :param ArrayBuffer buffer:
+         The content of the file.
 
-Static Method Descriptions
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+   .. js:function:: prototype.requestQuit( )
 
-.. js:method:: Engine.load(basePath)
+      Request that the current instance quit.
 
-    Load the engine from the specified base path.
+      This is akin the user pressing the close button in the window manager, and will
+      have no effect if the engine has crashed, or is stuck in a loop.
 
-    :param string basePath:
-        Base path of the engine to load.
-    :returns:
-        Promise which resolves once the engine is loaded.
+Engine configuration
+--------------------
 
-.. js:method:: Engine.unload()
+An object used to configure the Engine instance based on godot export options, and to override those in custom HTML
+templates if needed.
 
-    Unload the engine to free memory.
+Properties
+^^^^^^^^^^
 
-    This method is called automatically once the engine is started unless
-    explicitly disabled using :js:meth:`engine.setUnloadAfterInit`.
++-------------------+-------------------------------+
+| type              | name                          |
++-------------------+-------------------------------+
+| boolean           | :js:attr:`unloadAfterInit`    |
++-------------------+-------------------------------+
+| HTMLCanvasElement | :js:attr:`canvas`             |
++-------------------+-------------------------------+
+| string            | :js:attr:`executable`         |
++-------------------+-------------------------------+
+| string            | :js:attr:`mainPack`           |
++-------------------+-------------------------------+
+| string            | :js:attr:`locale`             |
++-------------------+-------------------------------+
+| number            | :js:attr:`canvasResizePolicy` |
++-------------------+-------------------------------+
+| Array.<string>    | :js:attr:`args`               |
++-------------------+-------------------------------+
+| function          | :js:attr:`onExecute`          |
++-------------------+-------------------------------+
+| function          | :js:attr:`onExit`             |
++-------------------+-------------------------------+
+| function          | :js:attr:`onProgress`         |
++-------------------+-------------------------------+
+| function          | :js:attr:`onPrint`            |
++-------------------+-------------------------------+
+| function          | :js:attr:`onPrintError`       |
++-------------------+-------------------------------+
 
-.. js:method:: Engine.isWebGLAvailable([majorVersion = 1])
+.. js:attribute:: EngineConfig
 
-    Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
+   The Engine configuration object. This is just a typedef, create it like a regular object, e.g.:
 
-    :param number majorVersion:
-        The major WebGL version to check for. Defaults to ``1`` for *WebGL 1.0*.
-    :returns:
-        ``true`` if the given major version of WebGL is available, ``false``
-        otherwise.
+   ``const MyConfig = { executable: 'godot', unloadAfterInit: false }``
 
-.. js:method:: Engine.setWebAssemblyFilenameExtension(extension)
+   **Property Descriptions**
 
-    Set an alternative filename extension for the WebAssembly module. By default
-    it is assumed to be ``wasm``.
+   .. js:attribute:: unloadAfterInit
 
-    :param string extension:
-        Filename extension without preceding dot.
+      Whether the unload the engine automatically after the instance is initialized.
 
+      :type: boolean
 
-Instance Property Descriptions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      :value: ``true``
 
-.. js:attribute:: engine.rtenv
+   .. js:attribute:: canvas
 
-    The runtime environment provided by Emscripten's ``Module``. For more information
-    refer to the `official documentation <https://emscripten.org/docs/api_reference/module.html>`__ on Emscripten.
+      The HTML DOM Canvas object to use.
 
-Instance Method Descriptions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      By default, the first canvas element in the document will be used is none is specified.
 
-.. js:class:: Engine
+      :type: HTMLCanvasElement
 
-    Create a new instance of the ``Engine`` class.
+      :value: ``null``
 
-.. js:method:: engine.init([basePath])
+   .. js:attribute:: executable
 
-    Initialize the engine instance. Optionally, pass the base path to the engine to load it,
-    if it hasn't been loaded yet. See :js:meth:`Engine.load`.
+      The name of the WASM file without the extension. (Set by Godot Editor export process).
 
-    :param string basePath:
-        Base path of the engine to load.
+      :type: string
 
-    :returns:
-        Promise that resolves once the engine is loaded and initialized.
+      :value: ``""``
 
-.. js:method:: engine.preloadFile(file[, path])
+   .. js:attribute:: mainPack
 
-    Load a file so it is available in the instance's file system once it runs. Must
-    be called **before** starting the instance.
+      An alternative name for the game pck to load. The executable name is used otherwise.
 
-    :param string|ArrayBuffer file:
-        If type is ``string``, the file will be loaded from that path.
+      :type: string
 
-        If type is ``ArrayBuffer`` or a view on one, the buffer will used as
-        the content of the file.
+      :value: ``null``
 
-    :param string path:
-        Path by which the file will be accessible. Required, if ``file`` is not
-        a string. If not passed, the path is derived from the URL of the loaded
-        file.
+   .. js:attribute:: locale
 
-    :returns:
-        Promise that resolves once the file is loaded.
+      Specify a language code to select the proper localization for the game.
 
-.. js:method:: engine.start([arg1, arg2, …])
+      The browser locale will be used if none is specified. See complete list of
+      :ref:`supported locales <doc_locales>`.
 
-    Start the instance of the engine, using the passed strings as
-    command line arguments. :js:meth:`engine.startGame` can be used
-    in typical cases instead.
+      :type: string
 
-    This will initialize the instance if it is not initialized. For manual
-    initialization, see :js:meth:`engine.init`. The engine must be loaded beforehand.
+      :value: ``null``
 
-    Fails if a canvas cannot be found on the page.
+   .. js:attribute:: canvasResizePolicy
 
-    :param string variadic:
-        Command line argument.
+      The canvas resize policy determines how the canvas should be resized by Godot.
 
-    :returns:
-        Promise that resolves once the engine started.
+      ``0`` means Godot won't do any resizing. This is useful if you want to control the canvas size from
+      javascript code in your template.
 
-.. js:method:: engine.startGame(execName, mainPack)
+      ``1`` means Godot will resize the canvas on start, and when changing window size via engine functions.
 
-    Start the game instance using the given executable URL and main pack URL.
+      ``2`` means Godot will adapt the canvas size to match the whole browser window.
 
-    This will initialize the instance if it is not initialized. For manual
-    initialization, see :js:meth:`engine.init`.
+      :type: number
 
-    This will load the engine if it is not loaded. The base path of the
-    executable URL will be used as the engine base path.
+      :value: ``2``
 
-    :param string execName:
-        Executable name in a form of URL, omitting filename extension.
+   .. js:attribute:: args
 
-    :param string mainPack:
-        URL of the main pack to start the game.
+      The arguments to be passed as command line arguments on startup.
 
-    :returns:
-        Promise that resolves once the game started.
+      See :ref:`command line tutorial <doc_command_line_tutorial>`.
 
-.. js:method:: engine.setUnloadAfterInit(enabled)
+      **Note**: :js:meth:`startGame <Engine.prototype.startGame>` will always add the ``--main-pack`` argument.
 
-    Specify whether the engine will be unloaded automatically after the
-    instance is initialized. Enabled by default.
+      :type: Array.<string>
 
-    :param boolean enabled:
-        ``true`` if the engine shall be unloaded after initializing,
-        ``false`` otherwise.
+      :value: ``[]``
 
-.. js:method:: engine.setCanvas(canvasElem)
+   .. js:function:: onExecute( path, args )
 
-    Specify a canvas HTML element to use. By default, the first canvas element
-    on the page is used for rendering.
+      A callback function for handling Godot's ``OS.execute`` calls.
 
-    :param HTMLCanvasElement canvasElem:
-        The canvas element to use.
+      This is for example used in the Web Editor template to switch between project manager and editor, and for running the game.
 
-.. js:method:: engine.setCanvasResizedOnStart(enabled)
+      :param string path:
+         The path that Godot's wants executed.
 
-    Specifies whether the canvas will be resized to the width and height
-    specified in the project settings on start. Enabled by default.
+      :param Array.<string> args:
+         The arguments of the "command" to execute.
 
-    :param boolean enabled:
-        ``true`` if the canvas shall be resized on start, ``false`` otherwise.
+   .. js:function:: onExit( status_code )
 
-.. js:method:: engine.setLocale(locale)
+      A callback function for being notified when the Godot instance quits.
 
-    Specify a language code to select the proper localization for the game.
+      **Note**: This function will not be called if the engine crashes or become unresponsive.
 
-    .. seealso:: Complete list of :ref:`supported locales <doc_locales>`.
+      :param number status_code:
+         The status code returned by Godot on exit.
 
-    :param string locale:
-        Language code.
+   .. js:function:: onProgress( current, total )
 
-.. js:method:: engine.setExecutableName(execName)
+      A callback function for displaying download progress.
 
-    Specify the virtual filename of the executable. By default, the base name
-    of the loaded engine files is used.
+      The function is called once per frame while downloading files, so the usage of ``requestAnimationFrame()``
+      is not necessary.
 
-    This affects the output of :ref:`OS.get_executable_path() <class_OS_method_get_executable_path>`
-    and sets the automatically started main pack to :file:`{ExecutableName}.pck`.
+      If the callback function receives a total amount of bytes as 0, this means that it is impossible to calculate.
+      Possible reasons include:
 
-    :param string execName:
-        Executable name.
+      -  Files are delivered with server-side chunked compression
+      -  Files are delivered with server-side compression on Chromium
+      -  Not all file downloads have started yet (usually on servers without multi-threading)
 
-.. js:method:: engine.setProgressFunc(callback)
+      :param number current:
+         The current amount of downloaded bytes so far.
 
-    Specify a callback function for displaying download progress. The callback function is
-    called once per frame, so that the usage of ``requestAnimationFrame()`` is not necessary.
+      :param number total:
+         The total amount of bytes to be downloaded.
 
-    If the callback function receives a total amount of bytes as 0, this means that
-    it is impossible to calculate. Possible reasons include:
+   .. js:function:: onPrint( [ ...var_args ] )
 
-     -  Files are delivered with server-side chunked compression
-     -  Files are delivered with server-side compression on Chromium
-     -  Not all file downloads have started yet (usually on servers without
-        multi-threading)
+      A callback function for handling the standard output stream. This method should usually only be used in debug pages.
 
-    :param function callback:
-        The callback function must accept two numeric arguments: the amount of bytes
-        loaded so far, and the total number of bytes to load.
+      By default, ``console.log()`` is used.
 
-.. js:method:: engine.setStdoutFunc(callback)
+      :param * var_args:
+         A variadic number of arguments to be printed.
 
-    Specify a callback function for handling the standard output stream. This method
-    should usually only be used in debug pages. By default, ``console.log()`` is used.
+   .. js:function:: onPrintError( [ ...var_args ] )
 
-    :param function callback:
-        The callback function must accept one string argument: the message to print.
+      A callback function for handling the standard error stream. This method should usually only be used in debug pages.
 
-.. js:method:: engine.setStderrFunc(callback)
+      By default, ``console.error()`` is used.
 
-    Specify a callback function for handling the standard error stream. This method
-    should usually only be used in debug pages. By default, ``console.warn()`` is used.
+      :param * var_args:
+         A variadic number of arguments to be printed as errors.
 
-    :param function callback:
-        The callback function must accept one string argument: the message to print.