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,47 @@
+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, set :ref:`Project Settings > 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 true in a boolean context, the rest of the function will run as expected; if it is false in a boolean context, then the project will stop.
+
+If ``assert()`` is passed something guaranteed to be false in a boolean context, then the ``assert()`` call will always stop the project.
+
+.. code-block::
+
+    # Zero always evaluates to false.
+    assert(0, "Zero is false in a boolean context")
+
+    # Likewise, an empty string always evaluates to false.
+    assert("", "An empty string is false in a boolean context")
+
+.. note::
+
+    Godot will *not* raise this warning if a literal false boolean is passed:
+
+    .. code-block::
+
+        # Despite false being passed, this won't raise ASSERT_ALWAYS_FALSE.
+        assert(false, "False is false")
+
+    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, set :ref:`Project Settings > 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, set :ref:`Project Settings > 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, set :ref:`Project Settings > 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 (such as 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 prefer 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, set :ref:`Project Settings > 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, set :ref:`Project Settings > 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, set :ref:`Project Settings > 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, set :ref:`Project Settings > 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, set :ref:`Project Settings > 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 the default value of a node's property 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, set :ref:`Project Settings > Debug > GDScript > Warnings > Get Node Default Without Onready<class_ProjectSettings_property_debug/gdscript/warnings/get_node_default_without_onready>`.
+
+When this warning occurs
+------------------------
+
+Instance properties 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
+
+The property ``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 a property's default value be a particular child node, it may be tempting to write something like the following::
+
+.. code-block::
+
+    extends Area2D
+
+    var my_collision_shape = $CollisionShape2D
+
+However, properties' 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 property declaration::
+
+.. code-block::
+
+    extends Area2D
+
+    @onready var my_collision_shape = $CollisionShape2D
+
+Now, the default value of the property will not be assigned until the scene tree has been initialized, and the node will be present.
+
+Alternatively, you can set the value of the property at the beginning of your ``_ready()`` method::
+
+.. code-block::
+
+    extends Area2D
+
+    var my_collision_shape
+
+    func _ready():
+        my_collision_shape = $CollisionShape2D