Add GDScript warning pages

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -1593,6 +1593,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,4 +16,5 @@ GDScript
    gdscript_styleguide
    static_typing
    warning_system
+   warnings/index
    gdscript_format_string

tutorials/scripting/gdscript/warnings/get_node_default_without_onready.rst

@@ -0,0 +1,55 @@
+GET_NODE_DEFAULT_WITHOUT_ONREADY
+================================
+
+This warning appears when a node's property is initialized to a node 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 uses "get_node()" which won't return nodes in the scene tree before "_ready()" is called. Use the "@onready" annotation to solve this.
+
+    The default value uses "$" which won't return nodes in the scene tree before "_ready()" is called. Use the "@onready" annotation to solve this.
+
+    The default value uses "%" 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
+------------------------
+
+This warning may appear when attempting to assign the default value of a property
+to a node in the scene tree, like so:
+
+.. code-block:: gdscript
+
+    extends Area2D
+
+    # Will give warning GET_NODE_DEFAULT_WITHOUT_ONREADY.
+    var my_collision_shape = $CollisionShape2D
+
+If you want a property to refer to another node in the scene tree, you may be inclined
+to reference it using :ref:`get_node() <class_Node_method_get_node>`
+(or the ``$`` and ``%`` shorthand versions) when setting its default value.
+
+However, properties' default values are evaluated and assigned *before* nodes are added to the scene tree.
+This means that when the script tries to assign that value, it won't be able to find the node it's looking for,
+because it isn't a part of the scene tree containing that node yet.
+As a result, the property will be set to ``null`` instead.
+
+How to fix this warning
+-----------------------
+
+Add the ``@onready`` annotation before your property declaration:
+
+.. code-block:: gdscript
+
+    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,
+at which time the node will be present.

tutorials/scripting/gdscript/warnings/index.rst

@@ -0,0 +1,27 @@
+:allow_comments: False
+
+.. _doc_gdscript_warnings:
+
+GDScript warnings
+=================
+
+This is a collection of warnings that GDScript can emit, and information on how to fix the code that causes them.
+
+.. note::
+
+   The list of warnings is currently incomplete. We hope to add pages for more warnings over time,
+   so that each one can be thoroughly reviewed for correctness and clarity.
+
+.. rubric:: Warnings
+   :heading-level: 2
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-gdscript-warnings
+
+   get_node_default_without_onready
+   integer_division
+   return_value_discarded
+   shadowed_variable
+   unassigned_variable
+   unused_variable

tutorials/scripting/gdscript/warnings/integer_division.rst

@@ -0,0 +1,43 @@
+INTEGER_DIVISION
+================
+
+The warning message is:
+
+.. code-block:: none
+
+    Integer division. Decimal part will be discarded.
+
+The default warning level for this warning is **Warn**.
+To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Integer Division<class_ProjectSettings_property_debug/gdscript/warnings/integer_division>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear when attempting to divide two integers:
+
+.. code-block::
+
+    var result = 5 / 3  # Will give warning INTEGER_DIVISION.
+
+Because both operands are integers, the result will be an integer as well.
+Integers can't store fractional parts of numbers, so the result must be a whole number.
+Godot discards anything after the decimal point in the mathematical result to obtain the integer result.
+**Note that the number is not rounded to the nearest whole number.**
+
+
+How to fix this warning
+-----------------------
+
+Use a floating-point number (``float``) for at least one operand of the division operation:
+
+.. code-block::
+
+    var result = 5.0 / 3
+
+If the integers being divided are variables, cast them to ``float``:
+
+.. code-block::
+
+    var a: int = 5
+    var b: int = 3
+    var result = float(a) / float(b)

tutorials/scripting/gdscript/warnings/return_value_discarded.rst

@@ -0,0 +1,42 @@
+RETURN_VALUE_DISCARDED
+======================
+
+The warning message is:
+
+.. code-block:: none
+
+    The function "get_number()" returns a value that will be discarded if not used.
+
+The default warning level for this warning is **Ignore**.
+To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Return Value Discarded<class_ProjectSettings_property_debug/gdscript/warnings/return_value_discarded>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear if a method returns a value, but that value is not used
+in an expression or assigned to a variable:
+
+.. code-block::
+
+    func _ready():
+        print("About to get a number...")
+        get_number()  # Will give warning RETURN_VALUE_DISCARDED.
+        print("Got a number!")
+
+    func get_number() -> int:
+        return 5
+
+How to fix this warning
+-----------------------
+
+Assign the returned value to a variable for use later.
+
+.. code-block::
+
+    func _ready():
+        print("About to get a number...")
+        var num = get_number()
+        print("Got a number! It's %s" % num)
+
+However, some methods in Godot's APIs return values that are not necessary to store.
+As such, depending on the situation, it may make more sense to ignore this warning.

tutorials/scripting/gdscript/warnings/shadowed_variable.rst

@@ -0,0 +1,40 @@
+SHADOWED_VARIABLE
+=================
+
+The warning message is:
+
+.. code-block:: none
+
+    The local variable "level" is shadowing an already-declared variable at line 3 in the current class.
+
+The default warning level for this warning is **Warn**.
+To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Shadowed Variable<class_ProjectSettings_property_debug/gdscript/warnings/shadowed_variable>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear when giving something the same name as a variable previously
+defined in the class.
+
+.. code-block::
+
+    extends Node
+
+    var level = 3
+
+    func _ready():
+        # Will give warning SHADOWED_VARIABLE.
+        var level = 1
+        print("Time for level %s" % level)
+
+In this example, the script class has a property ``level`` which can be accessed from its functions.
+However, at the first line of ``_ready()``, a new ``level`` variable is declared for that function specifically.
+After this declaration, any references to ``level`` will go to that version and not the shared variable for the class.
+This is called *shadowing*.
+
+
+How to fix this warning
+-----------------------
+
+Change the name to something that isn't being used by the class.
+For example, if receiving a warning about using the identifier ``level``, consider using something more descriptive like ``new_level``.

tutorials/scripting/gdscript/warnings/unassigned_variable.rst

@@ -0,0 +1,35 @@
+UNASSIGNED_VARIABLE
+===================
+
+The warning message is:
+
+.. code-block:: none
+
+    The variable "my_var" is used before being assigned a value.
+
+The default warning level for this warning is **Warn**.
+To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Unassigned Variable<class_ProjectSettings_property_debug/gdscript/warnings/unassigned_variable>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear when attempting to use a variable that hasn't had a value
+assigned to it yet.
+
+.. code-block::
+
+    var my_var
+    print(my_var)
+
+By default, the variable will be ``null``. However, Godot considers this a warning
+because the user did not explicitly assign the value, and as such might be unaware of it.
+
+How to fix this warning
+-----------------------
+
+Assign a value to the variable before including it in an expression or function call:
+
+.. code-block::
+
+    var my_var = 5
+    print(my_var)

tutorials/scripting/gdscript/warnings/unused_variable.rst

@@ -0,0 +1,52 @@
+UNUSED_VARIABLE
+===============
+
+The warning message is:
+
+.. code-block:: none
+
+    The local variable "counter" is declared but never used in the block. If this is intended, prefix it with an underscore: "_counter".
+
+The default warning level for this warning is **Warn**.
+To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Unused Variable<class_ProjectSettings_property_debug/gdscript/warnings/unused_variable>`.
+
+When this warning occurs
+------------------------
+
+This warning may appear when a variable is declared, but never used before its
+function or scope ends:
+
+.. code-block::
+
+    extends CharacterBody2D
+
+    func _process(delta):
+        var player_speed = 5.0  # Will give warning UNUSED_VARIABLE.
+        velocity = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
+        move_and_slide()
+
+In this example, the variable ``player_speed`` is presumably meant to control how
+fast the player moves. However, ``velocity`` never actually takes into account
+this speed variable; it only uses the result of ``Input.get_vector()``.
+It's likely that the programmer meant to include ``player_speed`` here somehow but forgot to write it.
+
+How to fix this warning
+-----------------------
+
+If a variable is being marked as unused, you probably meant to use it somewhere
+but forgot to include it in the relevant statement. Following the example above,
+the likely solution would be to incorporate it into the calculation of ``velocity``:
+
+.. code-block::
+
+    velocity = player_speed * Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
+
+If you're certain you don't need the variable for anything right now, but might
+need its value later on, prefix its name with an underscore (``_``) as the warning text suggests.
+Once you start referencing it elsewhere in the code, you can remove the underscore.
+
+.. code-block::
+
+    var _player_speed = 5.0  # Will not give warning UNUSED_VARIABLE.
+
+If you know you won't ever need the variable, then simply delete it.