Add GDScript warning pages

tutorials/scripting/gdscript/index.rst

@@ -14,6 +14,7 @@ GDScript
    gdscript_styleguide
    static_typing
    warning_system
+   warnings/index
    gdscript_format_string
 
 .. seealso::

tutorials/scripting/gdscript/warnings/assert_always_false.rst

@@ -0,0 +1,51 @@
+ASSERT_ALWAYS_FALSE
+=======================
+
+The warning message is:
+
+.. code-block:: none
+
+    Assert statement will raise an error because the expression is always false.
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/assert_always_false<class_ProjectSettings_property_debug/gdscript/warnings/assert_always_false>`.
+
+When this warning occurs
+------------------------
+
+The :ref:`assert() <class_@GDScript_method_assert>` keyword can be used to ensure that a given condition is met before allowing code execution to continue. If the first argument passed to it is truthy, the rest of the function will run as expected; if it is falsy, then the project will stop.
+
+If ``assert()`` is passed something guaranteed to be falsy, then the ``assert()`` call will always stop the project.
+
+.. code-block::
+
+    # Zero always evaluates to false.
+    assert(0, "Zero is falsy")
+
+    # Likewise, an empty string always evaluates to false.
+    assert("", "An empty string is falsy")
+
+.. note::
+
+    Godot will *not* raise this warning if a literal falsy boolean is passed:
+
+    .. code-block::
+
+        # Despite false being passed, this won't raise ASSERT_ALWAYS_FALSE.
+        assert(false, "False is false")
+
+        # This evaluates to a boolean which is false, so it also won't raise
+        # the warning.
+        assert(3 == 4, "3 isn't equal to 4")
+
+    This is because ``assert(false)`` calls are often used in development to forcibly halt program execution and avoid strange errors later on.
+
+    See `GH-58087 <https://github.com/godotengine/godot/issues/58087>`_ for more information.
+
+How to fix this warning
+-----------------------
+
+Assuming you want code following the ``assert()`` to run, remove it from your code. If you do want code execution to stop at that point, replace the condition with ``false``, or :ref:`consider using breakpoints instead <doc_debugger_tools_and_options>`.
+
+
+

tutorials/scripting/gdscript/warnings/assert_always_true.rst

@@ -0,0 +1,36 @@
+ASSERT_ALWAYS_TRUE
+======================
+
+The warning message is:
+
+.. code-block:: none
+
+    Assert statement is redundant because the expression is always true.
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/assert_always_true<class_ProjectSettings_property_debug/gdscript/warnings/assert_always_true>`.
+
+When this warning occurs
+------------------------
+
+The :ref:`assert() <class_@GDScript_method_assert>` keyword can be used to ensure that a given condition is met before allowing code execution to continue. If the first argument passed to it evaluates to ``true``, the rest of the function will run as expected; if it is ``false``, then the project will stop.
+
+If ``assert()`` is passed an expression that is guaranteed to be ``true``, then the ``assert()`` call will never stop the project, thus making it redundant.
+
+.. code-block::
+
+    # The boolean true will always be true, so this assert will never stop
+    # the program.
+    assert(true, "True is false, somehow?")
+
+    # Likewise, 3 will never be equal to 4, so this assert will never stop
+    # the program.
+    assert(3 != 4, "3 is equal to 4")
+
+How to fix this warning
+-----------------------
+
+Remove the ``assert()`` statement from your code.
+
+
+

tutorials/scripting/gdscript/warnings/confusable_capture_reassignment.rst

@@ -0,0 +1,25 @@
+CONFUSABLE_CAPTURE_REASSIGNMENT
+===================================
+
+The warning message is:
+
+.. code-block:: none
+
+    Reassigning lambda capture does not modify the outer local variable "my_var".
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/confusable_capture_reassignment<class_ProjectSettings_property_debug/gdscript/warnings/confusable_capture_reassignment>`.
+
+When this warning occurs
+------------------------
+
+TODO
+
+
+How to fix this warning
+-----------------------
+
+TODO
+
+
+

tutorials/scripting/gdscript/warnings/confusable_identifier.rst

@@ -0,0 +1,31 @@
+CONFUSABLE_IDENTIFIER
+=========================
+
+The warning message is:
+
+.. code-block:: none
+
+    The identifier "my_vаr" has misleading characters and might be confused with something else.
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/confusable_identifier<class_ProjectSettings_property_debug/gdscript/warnings/confusable_identifier>`.
+
+When this warning occurs
+------------------------
+
+Some alphabets such as Cyrillic have characters that look like Latin (i.e., English, Spanish, etc.) characters, but are actually different.
+
+.. code-block::
+
+    var engine_nаme = "Godot"
+    print(engine_name)
+
+In this code snippet, the ``print`` statement would fail, because ``engine_name`` is actually not defined. The identifier in the ``print`` statement uses the Latin character "a" (U+0061), while the identifier in the variable declaration above uses the Cyrillic character "а" (U+0430).
+
+How to fix this warning
+-----------------------
+
+Avoid using Cyrillic or other alphabets' characters that are visually similar to Latin ones. A good rule of thumb is to always use the Latin alphabet for program identifiers.
+
+
+

tutorials/scripting/gdscript/warnings/confusable_local_declaration.rst

@@ -0,0 +1,25 @@
+CONFUSABLE_LOCAL_DECLARATION
+================================
+
+The warning message is:
+
+.. code-block:: none
+
+    The variable "my_param" is declared below in the parent block.
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/confusable_local_declaration<class_ProjectSettings_property_debug/gdscript/warnings/confusable_local_declaration>`.
+
+When this warning occurs
+------------------------
+
+TODO
+
+
+How to fix this warning
+-----------------------
+
+TODO
+
+
+

tutorials/scripting/gdscript/warnings/confusable_local_usage.rst

@@ -0,0 +1,25 @@
+CONFUSABLE_LOCAL_USAGE
+==========================
+
+The warning message is:
+
+.. code-block:: none
+
+    The identifier "my_var" will be shadowed below in the block.
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/confusable_local_usage<class_ProjectSettings_property_debug/gdscript/warnings/confusable_local_usage>`.
+
+When this warning occurs
+------------------------
+
+TODO
+
+
+How to fix this warning
+-----------------------
+
+TODO
+
+
+

tutorials/scripting/gdscript/warnings/deprecated_keyword.rst

@@ -0,0 +1,25 @@
+DEPRECATED_KEYWORD
+======================
+
+The warning message is:
+
+.. code-block:: none
+
+    The "..." keyword is deprecated and will be removed in a future release, please replace its uses by "...".
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/deprecated_keyword<class_ProjectSettings_property_debug/gdscript/warnings/deprecated_keyword>`.
+
+When this warning occurs
+------------------------
+
+There are currently no deprecated keywords in GDScript; as such, this warning should never appear.
+
+
+How to fix this warning
+-----------------------
+
+Follow instructions on the Godot Docs for how to use the alternative keyword.
+
+
+

tutorials/scripting/gdscript/warnings/empty_file.rst

@@ -0,0 +1,24 @@
+EMPTY_FILE
+==============
+
+The warning message is:
+
+.. code-block:: none
+
+    Empty script file.
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/empty_file<class_ProjectSettings_property_debug/gdscript/warnings/empty_file>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear when you create a ``.gd`` file with no code to run. A completely blank file will raise this warning, as will a file that only contains comments.
+
+How to fix this warning
+-----------------------
+
+Add code to the ``.gd`` file or delete it.
+
+
+

tutorials/scripting/gdscript/warnings/enum_variable_without_default.rst

@@ -0,0 +1,55 @@
+ENUM_VARIABLE_WITHOUT_DEFAULT
+=================================
+
+The warning message is:
+
+.. code-block:: none
+
+    The variable "my_var" has an enum type and does not set an explicit default value. The default will be set to "0".
+
+The default warning level for this warning is **Warn**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/enum_variable_without_default<class_ProjectSettings_property_debug/gdscript/warnings/enum_variable_without_default>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear when declaring a variable whose type is an enum with values assigned to its members, but the variable is not assigned a value.
+
+.. code-block::
+
+    enum MyEnum {
+        A = 1,
+        B = 2,
+        C = 3
+    }
+
+    func _ready():
+        var my_var: MyEnum  # Will give warning ENUM_VARIABLE_WITHOUT_DEFAULT.
+
+Godot will usually default an enum-typed variable to the integer 0. However, if the enum does not have a member that corresponds to 0, Godot will be confused on how to assign it.
+
+How to fix this warning
+-----------------------
+
+Provide the variable with a default value, like so:
+
+.. code-block::
+
+    var my_var: MyEnum = MyEnum.A
+
+Alternatively, if the enum has a member with a value of 0, Godot will use that as the default value.
+
+.. code-block::
+
+    enum MyEnum {
+        Z = 0,  # Will be used as the default value.
+        A = 1,
+        B = 2,
+        C = 3
+    }
+
+    func _ready():
+        var my_var: MyEnum  # Will default to MyEnum.Z.
+
+
+

tutorials/scripting/gdscript/warnings/get_node_default_without_onready.rst

@@ -0,0 +1,63 @@
+GET_NODE_DEFAULT_WITHOUT_ONREADY
+====================================
+
+This warning appears when a node's default value is set to a location in the scene tree without using the ``@onready`` annotation.
+
+Depending on how you attempt to access the scene tree, the warning message will be one of the following:
+
+.. code-block:: none
+
+    The default value is using "$" which won't return nodes in the scene tree before "_ready()" is called. Use the "@onready" annotation to solve this.
+
+    The default value is using "%" which won't return nodes in the scene tree before "_ready()" is called. Use the "@onready" annotation to solve this.
+
+    The default value is using "get_node()" which won't return nodes in the scene tree before "_ready()" is called. Use the "@onready" annotation to solve this.
+
+The default warning level for this warning is **Error**.
+To modify it, see :ref:`ProjectSettings.debug/gdscript/warnings/get_node_default_without_onready<class_ProjectSettings_property_debug/gdscript/warnings/get_node_default_without_onready>`.
+
+When this warning occurs
+------------------------
+
+In GDScript, instance variables can be set by declaring them outside of a method. Additionally, they can be given a default value using ``=``::
+
+.. code-block::
+
+    extends Area2D
+
+    var my_num = 3
+
+This way, the variable ``my_num`` will always start out with a value of ``3`` in each instance of this class.
+GDScript also has methods to retrieve specific nodes from the scene tree: namely, the :ref:`get_node() <class_Node_method_get_node>` method, and its shorthand versions ``$`` (and ``%`` for unique nodes). Thus, if you want to have an instance variable default to a child of the node with a script, it may be tempting to write something like the following::
+
+.. code-block::
+
+    extends Area2D
+
+    var my_collision_shape = $CollisionShape2D
+
+However, class instance variables' default values are evaluated and assigned before the scene tree is set up. This means that at the time of assigning the default value, the node may not be in the scene tree, and the variable will be set to ``null`` instead.
+
+How to fix this warning
+-----------------------
+
+The most straightforward solution is to add the ``@onready`` annotation before your variable declaration::
+
+.. code-block::
+
+    extends Area2D
+
+    @onready var my_collision_shape = $CollisionShape2D
+
+Now, the default value of the variable will not be assigned until the scene tree has been initialized, and the target node will be present.
+
+Alternatively, you can set the value of the variable at the beginning of your ``_ready()`` method::
+
+.. code-block::
+
+    extends Area2D
+
+    var my_collision_shape
+
+    func _ready():
+        my_collision_shape = $CollisionShape2D