Revert "Update HTML5 classref with autogenerated jsdoc."

This reverts commit 58690b4c0a6b3b17481d9d47f4073c5ad10df598.

tutorials/platform/html5_shell_classref.rst

@@ -3,7 +3,7 @@
 HTML5 shell class reference
 ===========================
 
-Projects exported for the Web expose the :js:class:`Engine` class to the JavaScript environment, that allows
+Projects exported for the Web expose the ``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,334 +19,248 @@ see :ref:`Custom HTML page for Web export <doc_customizing_html5_shell>`.
 Static Methods
 ^^^^^^^^^^^^^^
 
-+---------+-----------------------------------------------------------------------------------------------+
-| Promise | :js:attr:`load <Engine.load>` **(** string basePath **)**                                     |
-+---------+-----------------------------------------------------------------------------------------------+
-| void    | :js:attr:`unload <Engine.unload>` **(** **)**                                                 |
-+---------+-----------------------------------------------------------------------------------------------+
-| boolean | :js:attr:`isWebGLAvailable <Engine.isWebGLAvailable>` **(** *[ number majorVersion=1 ]* **)** |
-+---------+-----------------------------------------------------------------------------------------------+
++---------+-------------------------------------------------------------------------------------------------------------------+
+| 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 Methods
-^^^^^^^^^^^^^^^^
-
-+---------+---------------------------------------------------------------------------------------------------------------+
-| 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
+Instance Properties
+^^^^^^^^^^^^^^^^^^^
 
-   .. js:function:: prototype.preloadFile( file [, path ] )
++-----------------------+----------------------------------+
+| Emscripten ``Module`` | `engine.rtenv <#engine.rtenv>`__ |
++-----------------------+----------------------------------+
 
-      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.
+Instance Methods
+^^^^^^^^^^^^^^^^
 
-      :param string path:
-         The location where the file will be created.
++---------+------------------------------------------------------------------------------------------------------+
+| 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 **)**                       |
++---------+------------------------------------------------------------------------------------------------------+
 
-      :param ArrayBuffer buffer:
-         The content of the file.
 
-   .. js:function:: prototype.requestQuit( )
+Static Method Descriptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      Request that the current instance quit.
+.. js:method:: Engine.load(basePath)
 
-      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.
+    Load the engine from the specified base path.
 
-Engine configuration
---------------------
+    :param string basePath:
+        Base path of the engine to load.
+    :returns:
+        Promise which resolves once the engine is loaded.
 
-An object used to configure the Engine instance based on godot export options, and to override those in custom HTML
-templates if needed.
+.. js:method:: Engine.unload()
 
-Properties
-^^^^^^^^^^
+    Unload the engine to free memory.
 
-+-------------------+-------------------------------+
-| 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`       |
-+-------------------+-------------------------------+
+    This method is called automatically once the engine is started unless
+    explicitly disabled using :js:meth:`engine.setUnloadAfterInit`.
 
-.. js:attribute:: EngineConfig
+.. js:method:: Engine.isWebGLAvailable([majorVersion = 1])
 
-   The Engine configuration object. This is just a typedef, create it like a regular object, e.g.:
+    Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
 
-   ``const MyConfig = { executable: 'godot', unloadAfterInit: false }``
+    :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.
 
-   **Property Descriptions**
+.. js:method:: Engine.setWebAssemblyFilenameExtension(extension)
 
-   .. js:attribute:: unloadAfterInit
+    Set an alternative filename extension for the WebAssembly module. By default
+    it is assumed to be ``wasm``.
 
-      Whether the unload the engine automatically after the instance is initialized.
+    :param string extension:
+        Filename extension without preceding dot.
 
-      :type: boolean
 
-      :value: ``true``
+Instance Property Descriptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   .. js:attribute:: canvas
+.. js:attribute:: engine.rtenv
 
-      The HTML DOM Canvas object to use.
+    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.
 
-      By default, the first canvas element in the document will be used is none is specified.
+Instance Method Descriptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      :type: HTMLCanvasElement
+.. js:class:: Engine
 
-      :value: ``null``
+    Create a new instance of the ``Engine`` class.
 
-   .. js:attribute:: executable
+.. js:method:: engine.init([basePath])
 
-      The name of the WASM file without the extension. (Set by Godot Editor export process).
+    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`.
 
-      :type: string
+    :param string basePath:
+        Base path of the engine to load.
 
-      :value: ``""``
+    :returns:
+        Promise that resolves once the engine is loaded and initialized.
 
-   .. js:attribute:: mainPack
+.. js:method:: engine.preloadFile(file[, path])
 
-      An alternative name for the game pck to load. The executable name is used otherwise.
+    Load a file so it is available in the instance's file system once it runs. Must
+    be called **before** starting the instance.
 
-      :type: string
+    :param string|ArrayBuffer file:
+        If type is ``string``, the file will be loaded from that path.
 
-      :value: ``null``
+        If type is ``ArrayBuffer`` or a view on one, the buffer will used as
+        the content of the file.
 
-   .. js:attribute:: locale
+    :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.
 
-      Specify a language code to select the proper localization for the game.
+    :returns:
+        Promise that resolves once the file is loaded.
 
-      The browser locale will be used if none is specified. See complete list of
-      :ref:`supported locales <doc_locales>`.
+.. js:method:: engine.start([arg1, arg2, …])
 
-      :type: string
+    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.
 
-      :value: ``null``
+    This will initialize the instance if it is not initialized. For manual
+    initialization, see :js:meth:`engine.init`. The engine must be loaded beforehand.
 
-   .. js:attribute:: canvasResizePolicy
+    Fails if a canvas cannot be found on the page.
 
-      The canvas resize policy determines how the canvas should be resized by Godot.
+    :param string variadic:
+        Command line argument.
 
-      ``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.
+    :returns:
+        Promise that resolves once the engine started.
 
-      ``1`` means Godot will resize the canvas on start, and when changing window size via engine functions.
+.. js:method:: engine.startGame(execName, mainPack)
 
-      ``2`` means Godot will adapt the canvas size to match the whole browser window.
+    Start the game instance using the given executable URL and main pack URL.
 
-      :type: number
+    This will initialize the instance if it is not initialized. For manual
+    initialization, see :js:meth:`engine.init`.
 
-      :value: ``2``
+    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.
 
-   .. js:attribute:: args
+    :param string execName:
+        Executable name in a form of URL, omitting filename extension.
 
-      The arguments to be passed as command line arguments on startup.
+    :param string mainPack:
+        URL of the main pack to start the game.
 
-      See :ref:`command line tutorial <doc_command_line_tutorial>`.
+    :returns:
+        Promise that resolves once the game started.
 
-      **Note**: :js:meth:`startGame <Engine.prototype.startGame>` will always add the ``--main-pack`` argument.
+.. js:method:: engine.setUnloadAfterInit(enabled)
 
-      :type: Array.<string>
+    Specify whether the engine will be unloaded automatically after the
+    instance is initialized. Enabled by default.
 
-      :value: ``[]``
+    :param boolean enabled:
+        ``true`` if the engine shall be unloaded after initializing,
+        ``false`` otherwise.
 
-   .. js:function:: onExecute( path, args )
+.. js:method:: engine.setCanvas(canvasElem)
 
-      A callback function for handling Godot's ``OS.execute`` calls.
+    Specify a canvas HTML element to use. By default, the first canvas element
+    on the page is used for rendering.
 
-      This is for example used in the Web Editor template to switch between project manager and editor, and for running the game.
+    :param HTMLCanvasElement canvasElem:
+        The canvas element to use.
 
-      :param string path:
-         The path that Godot's wants executed.
+.. js:method:: engine.setCanvasResizedOnStart(enabled)
 
-      :param Array.<string> args:
-         The arguments of the "command" to execute.
+    Specifies whether the canvas will be resized to the width and height
+    specified in the project settings on start. Enabled by default.
 
-   .. js:function:: onExit( status_code )
+    :param boolean enabled:
+        ``true`` if the canvas shall be resized on start, ``false`` otherwise.
 
-      A callback function for being notified when the Godot instance quits.
+.. js:method:: engine.setLocale(locale)
 
-      **Note**: This function will not be called if the engine crashes or become unresponsive.
+    Specify a language code to select the proper localization for the game.
 
-      :param number status_code:
-         The status code returned by Godot on exit.
+    .. seealso:: Complete list of :ref:`supported locales <doc_locales>`.
 
-   .. js:function:: onProgress( current, total )
+    :param string locale:
+        Language code.
 
-      A callback function for displaying download progress.
+.. js:method:: engine.setExecutableName(execName)
 
-      The function is called once per frame while downloading files, so the usage of ``requestAnimationFrame()``
-      is not necessary.
+    Specify the virtual filename of the executable. By default, the base name
+    of the loaded engine files is used.
 
-      If the callback function receives a total amount of bytes as 0, this means that it is impossible to calculate.
-      Possible reasons include:
+    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`.
 
-      -  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)
+    :param string execName:
+        Executable name.
 
-      :param number current:
-         The current amount of downloaded bytes so far.
+.. js:method:: engine.setProgressFunc(callback)
 
-      :param number total:
-         The total amount of bytes to be downloaded.
+    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.
 
-   .. js:function:: onPrint( [ ...var_args ] )
+    If the callback function receives a total amount of bytes as 0, this means that
+    it is impossible to calculate. Possible reasons include:
 
-      A callback function for handling the standard output stream. This method should usually only be used in debug pages.
+     -  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)
 
-      By default, ``console.log()`` is used.
+    :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.
 
-      :param * var_args:
-         A variadic number of arguments to be printed.
+.. js:method:: engine.setStdoutFunc(callback)
 
-   .. js:function:: onPrintError( [ ...var_args ] )
+    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.
 
-      A callback function for handling the standard error stream. This method should usually only be used in debug pages.
+    :param function callback:
+        The callback function must accept one string argument: the message to print.
 
-      By default, ``console.error()`` is used.
+.. js:method:: engine.setStderrFunc(callback)
 
-      :param * var_args:
-         A variadic number of arguments to be printed as errors.
+    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 function callback:
+        The callback function must accept one string argument: the message to print.