Merge pull request #9103 from godotengine/classref/sync-68ad520

classref: Sync with current master branch (68ad520)

classes/class_@gdscript.rst

@@ -788,6 +788,10 @@ The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter, but value
 
 Make a script with static variables to not persist after all references are lost. If the script is loaded again the static variables will revert to their default values.
 
+\ **Note:** As annotations describe their subject, the :ref:`@static_unload<class_@GDScript_annotation_@static_unload>` annotation must be placed before the class definition and inheritance.
+
+\ **Warning:** Currently, due to a bug, scripts are never freed, even if :ref:`@static_unload<class_@GDScript_annotation_@static_unload>` annotation is used.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -877,6 +881,8 @@ An optional ``message`` can be shown in addition to the generic "Assertion faile
     assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check.
     assert(speed < 20, "the speed limit is 20") # Show a message.
 
+\ **Note:** :ref:`assert<class_@GDScript_method_assert>` is a keyword, not a function. So you cannot access it as a :ref:`Callable<class_Callable>` or use it inside expressions.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -955,7 +961,7 @@ Returns an array of dictionaries representing the current call stack. See also :
 
 Starting from ``_ready()``, ``bar()`` would print:
 
-.. code::
+.. code:: text
 
     [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}]
 
@@ -987,7 +993,7 @@ Returns the passed ``instance`` converted to a Dictionary. Can be useful for ser
 
 Prints out:
 
-.. code::
+.. code:: text
 
     [@subpath, @path, foo]
     [, res://test.gd, bar]
@@ -1010,7 +1016,7 @@ Returns ``true`` if ``value`` is an instance of ``type``. The ``type`` value mus
 
 - A :ref:`Script<class_Script>` (you can use any class, including inner one).
 
-Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays) and is more performant. Use the operator instead of this method if you do not need dynamic type checking.
+Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays). Use the operator instead of this method if you do not need dynamic type checking.
 
 Examples:
 
@@ -1091,6 +1097,8 @@ Returns a :ref:`Resource<class_Resource>` from the filesystem located at ``path`
     # Create instance of a scene.
     var diamond = preload("res://diamond.tscn").instantiate()
 
+\ **Note:** :ref:`preload<class_@GDScript_method_preload>` is a keyword, not a function. So you cannot access it as a :ref:`Callable<class_Callable>`.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -1105,7 +1113,7 @@ Like :ref:`@GlobalScope.print<class_@GlobalScope_method_print>`, but includes th
 
 The output in the console may look like the following:
 
-.. code::
+.. code:: text
 
     Test print
     At: res://test.gd:15:_process()
@@ -1126,7 +1134,7 @@ Prints a stack trace at the current code location. See also :ref:`get_stack<clas
 
 The output in the console may look like the following:
 
-.. code::
+.. code:: text
 
     Frame 0 - res://test.gd:16 in function '_process'
 
@@ -1175,7 +1183,7 @@ To iterate over an :ref:`Array<class_Array>` backwards, use:
 
 Output:
 
-.. code::
+.. code:: text
 
     9
     6
@@ -1190,7 +1198,7 @@ To iterate over :ref:`float<class_float>`, convert them in the loop.
 
 Output:
 
-.. code::
+.. code:: text
 
     0.3
     0.2

classes/class_@globalscope.rst

@@ -6849,7 +6849,7 @@ For complex use cases where multiple ranges are needed, consider using :ref:`Cur
 
 :ref:`int<class_int>` **rid_allocate_id**\ (\ )
 
-Allocates a unique ID which can be used by the implementation to construct a RID. This is used mainly from native extensions to implement servers.
+Allocates a unique ID which can be used by the implementation to construct an RID. This is used mainly from native extensions to implement servers.
 
 .. rst-class:: classref-item-separator
 
@@ -6861,7 +6861,7 @@ Allocates a unique ID which can be used by the implementation to construct a RID
 
 :ref:`RID<class_RID>` **rid_from_int64**\ (\ base\: :ref:`int<class_int>`\ )
 
-Creates a RID from a ``base``. This is used mainly from native extensions to build servers.
+Creates an RID from a ``base``. This is used mainly from native extensions to build servers.
 
 .. rst-class:: classref-item-separator
 

classes/class_acceptdialog.rst

@@ -72,9 +72,9 @@ Methods
    +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`Button<class_Button>` | :ref:`get_ok_button<class_AcceptDialog_method_get_ok_button>`\ (\ )                                                                                                                   |
    +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-   | |void|                      | :ref:`register_text_enter<class_AcceptDialog_method_register_text_enter>`\ (\ line_edit\: :ref:`Control<class_Control>`\ )                                                            |
+   | |void|                      | :ref:`register_text_enter<class_AcceptDialog_method_register_text_enter>`\ (\ line_edit\: :ref:`LineEdit<class_LineEdit>`\ )                                                          |
    +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-   | |void|                      | :ref:`remove_button<class_AcceptDialog_method_remove_button>`\ (\ button\: :ref:`Control<class_Control>`\ )                                                                           |
+   | |void|                      | :ref:`remove_button<class_AcceptDialog_method_remove_button>`\ (\ button\: :ref:`Button<class_Button>`\ )                                                                             |
    +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 .. rst-class:: classref-reftable-group
@@ -295,7 +295,7 @@ Returns the OK :ref:`Button<class_Button>` instance.
 
 .. rst-class:: classref-method
 
-|void| **register_text_enter**\ (\ line_edit\: :ref:`Control<class_Control>`\ )
+|void| **register_text_enter**\ (\ line_edit\: :ref:`LineEdit<class_LineEdit>`\ )
 
 Registers a :ref:`LineEdit<class_LineEdit>` in the dialog. When the enter key is pressed, the dialog will be accepted.
 
@@ -307,7 +307,7 @@ Registers a :ref:`LineEdit<class_LineEdit>` in the dialog. When the enter key is
 
 .. rst-class:: classref-method
 
-|void| **remove_button**\ (\ button\: :ref:`Control<class_Control>`\ )
+|void| **remove_button**\ (\ button\: :ref:`Button<class_Button>`\ )
 
 Removes the ``button`` from the dialog. Does NOT free the ``button``. The ``button`` must be a :ref:`Button<class_Button>` added with :ref:`add_button<class_AcceptDialog_method_add_button>` or :ref:`add_cancel_button<class_AcceptDialog_method_add_cancel_button>` method. After removal, pressing the ``button`` will no longer emit this dialog's :ref:`custom_action<class_AcceptDialog_signal_custom_action>` or :ref:`canceled<class_AcceptDialog_signal_canceled>` signals.
 

classes/class_array.rst

@@ -501,6 +501,12 @@ Returns the last element of the array. Prints an error and returns ``null`` if t
 
 Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array.
 
+::
+
+    var array = ["a", "b", "c", "c", "d", "e"]
+    print(array.bsearch("c", true))  # Prints 2, at the first matching element.
+    print(array.bsearch("c", false)) # Prints 4, after the last matching element, pointing to "d".
+
 \ **Note:** Calling :ref:`bsearch<class_Array_method_bsearch>` on an unsorted array results in unexpected behavior.
 
 .. rst-class:: classref-item-separator
@@ -515,6 +521,8 @@ Finds the index of an existing value (or the insertion index that maintains sort
 
 Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return ``true`` if the first argument is less than the second, and return ``false`` otherwise.
 
+\ **Note:** The custom method must accept the two arguments in any order, you cannot rely on that the first argument will always be from the array.
+
 \ **Note:** Calling :ref:`bsearch_custom<class_Array_method_bsearch_custom>` on an unsorted array results in unexpected behavior.
 
 .. rst-class:: classref-item-separator

classes/class_arraymesh.rst

@@ -234,7 +234,7 @@ The ``arrays`` argument is an array of arrays. Each of the :ref:`Mesh.ARRAY_MAX<
 
 The ``blend_shapes`` argument is an array of vertex data for each blend shape. Each element is an array of the same structure as ``arrays``, but :ref:`Mesh.ARRAY_VERTEX<class_Mesh_constant_ARRAY_VERTEX>`, :ref:`Mesh.ARRAY_NORMAL<class_Mesh_constant_ARRAY_NORMAL>`, and :ref:`Mesh.ARRAY_TANGENT<class_Mesh_constant_ARRAY_TANGENT>` are set if and only if they are set in ``arrays`` and all other entries are ``null``.
 
-The ``lods`` argument is a dictionary with :ref:`float<class_float>` keys and :ref:`PackedInt32Array<class_PackedInt32Array>` values. Each entry in the dictionary represents a LOD level of the surface, where the value is the :ref:`Mesh.ARRAY_INDEX<class_Mesh_constant_ARRAY_INDEX>` array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of a LOD also increases the distance that the objects has to be from the camera before the LOD is used.
+The ``lods`` argument is a dictionary with :ref:`float<class_float>` keys and :ref:`PackedInt32Array<class_PackedInt32Array>` values. Each entry in the dictionary represents an LOD level of the surface, where the value is the :ref:`Mesh.ARRAY_INDEX<class_Mesh_constant_ARRAY_INDEX>` array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used.
 
 The ``flags`` argument is the bitwise or of, as required: One value of :ref:`ArrayCustomFormat<enum_Mesh_ArrayCustomFormat>` left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, :ref:`Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE<class_Mesh_constant_ARRAY_FLAG_USE_DYNAMIC_UPDATE>`, :ref:`Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS<class_Mesh_constant_ARRAY_FLAG_USE_8_BONE_WEIGHTS>`, or :ref:`Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY<class_Mesh_constant_ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY>`.
 

classes/class_audiostream.rst

@@ -12,7 +12,7 @@ AudioStream
 
 **Inherits:** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
 
-**Inherited By:** :ref:`AudioStreamGenerator<class_AudioStreamGenerator>`, :ref:`AudioStreamMicrophone<class_AudioStreamMicrophone>`, :ref:`AudioStreamMP3<class_AudioStreamMP3>`, :ref:`AudioStreamOggVorbis<class_AudioStreamOggVorbis>`, :ref:`AudioStreamPolyphonic<class_AudioStreamPolyphonic>`, :ref:`AudioStreamRandomizer<class_AudioStreamRandomizer>`, :ref:`AudioStreamWAV<class_AudioStreamWAV>`
+**Inherited By:** :ref:`AudioStreamGenerator<class_AudioStreamGenerator>`, :ref:`AudioStreamInteractive<class_AudioStreamInteractive>`, :ref:`AudioStreamMicrophone<class_AudioStreamMicrophone>`, :ref:`AudioStreamMP3<class_AudioStreamMP3>`, :ref:`AudioStreamOggVorbis<class_AudioStreamOggVorbis>`, :ref:`AudioStreamPlaylist<class_AudioStreamPlaylist>`, :ref:`AudioStreamPolyphonic<class_AudioStreamPolyphonic>`, :ref:`AudioStreamRandomizer<class_AudioStreamRandomizer>`, :ref:`AudioStreamSynchronized<class_AudioStreamSynchronized>`, :ref:`AudioStreamWAV<class_AudioStreamWAV>`
 
 Base class for audio streams.