Add GDScript warning pages

Set up warnings page

Add page for each warning, and move content for `GET_NODE_DEFAULT_WITHOUT_ONREADY`

Apply suggestions from code review

Co-authored-by: tetrapod <[email protected]>

Remove inline code formatting from page titles

Improvements to `GET_NODE_DEFAULT_WITHOUT_ONREADY` prototype page

Add warning messages that display in editor (placeholder %s kept)

Wrote for `ASSERT_ALWAYS_FALSE` and ASSERT_ALWAYS_TRUE`

Improve documentation for `ASSERT_ALWAYS_FALSE`

Update tutorials/scripting/gdscript/warnings/ASSERT_ALWAYS_FALSE.rst

Co-authored-by: tetrapod <[email protected]>

Add default warning levels to pages

Update a few pages to use placeholder variable names

Use `snake_case` for page names

Use `snake_case` for page names

Replace `%s` in warnings with example strings

Remove unused warnings

Improve example message for `INFERRED_DECLARATION`

Change `DEPRECATED_KEYWORD` page to clarify that the warning should never appear

Add links to ProjectSettings's configuration variables for warning levels

Fix typo

Add doc for CONFUSABLE_IDENTIFIER

Add doc for EMPTY_FILE

Add doc for ENUM_VARIABLE_WITHOUT_DEFAULT

Add doc for INFERRED_DECLARATION

Add doc for INFERENCE_ON_VARIANT

Add docs for INT_AS_ENUM_WITHOUT_CAST, INT_AS_ENUM_WITHOUT_MATCH, and INTEGER_DIVISION

Add doc for NATIVE_METHOD_OVERRIDE

Add doc for RETURN_VALUE_DISCARDED

Add doc for SHADOWED_GLOBAL_IDENTIFIER

Add doc for SHADOWED_VARIABLE_BASE_CLASS

Add doc for SHADOWED_VARIABLE

Make formatting fixes

Add doc for STANDALONE_EXPRESSION

Add doc for STANDALONE_TERNARY

Add doc for STATIC_CALLED_ON_INSTANCE

Add comments to some GDScript snippets

Add doc for `UNASSIGNED_VARIABLE_OP_ASSIGN`

Add doc for UNASSIGNED_VARIABLE

Add doc for UNREACHABLE_CODE

Fix typo in UNREACHABLE_CODE

Add doc for UNSAFE_CALL_ARGUMENT

Apply suggestions from code review

Co-authored-by: Micky <[email protected]>

Replace "truthy" and "falsy" with "boolean context"

Improve wording in GET_NODE_DEFAULT_WITHOUT_ONREADY

Improve wording and flow in INT_AS_ENUM_WITHOUT_MATCH

Clarify for INTEGER_DIVISION that only one operand needs to be a float

Improve SHADOWED_GLOBAL_IDENTIFIER

Improve STATIC_CALLED_ON_INSTANCE

Clarify default value in UNASSIGNED_VARIABLE

Fix error in ASSERT_ALWAYS_FALSE

Update links to Project Settings to use correct casing

Co-authored-by: tetrapod <[email protected]>

Add links to "GDScript basics" page so the sections can be referenced

Author: Meorge

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -1146,6 +1146,9 @@ Member variables are initialized in the following order:
     To fix this, move the ``_data`` variable definition above the ``a`` definition
     or remove the empty dictionary assignment (``= {}``).
 
+
+.. _doc_gdscript_basics_static_variables:
+
 Static variables
 ~~~~~~~~~~~~~~~~
 
@@ -1557,6 +1560,9 @@ Lambda functions capture the local environment:
         lambda.call()
         print(a) # Prints `[1]`.
 
+
+.. _doc_gdscript_basics_static_functions:
+
 Static functions
 ~~~~~~~~~~~~~~~~
 

tutorials/scripting/gdscript/index.rst

@@ -16,6 +16,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