Skip to content

Commit 0b93260

Browse files
MeorgeMeorge
committed
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 <145553014+tetrapod00@users.noreply.github.com> 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 <145553014+tetrapod00@users.noreply.github.com> 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 <66727710+Mickeon@users.noreply.github.com> 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 <145553014+tetrapod00@users.noreply.github.com> Add links to "GDScript basics" page so the sections can be referenced Update warning text in a few documents Apply suggestions from code review Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> Add page for UNUSED_VARIABLE
1 parent d316eac commit 0b93260

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+1612
-0
lines changed

‎tutorials/scripting/gdscript/gdscript_basics.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1146,6 +1146,9 @@ Member variables are initialized in the following order:
11461146
To fix this, move the ``_data`` variable definition above the ``a`` definition
11471147
or remove the empty dictionary assignment (``= {}``).
11481148

1149+
1150+
.. _doc_gdscript_basics_static_variables:
1151+
11491152
Static variables
11501153
~~~~~~~~~~~~~~~~
11511154

@@ -1557,6 +1560,9 @@ Lambda functions capture the local environment:
15571560
lambda.call()
15581561
print(a) # Prints `[1]`.
15591562

1563+
1564+
.. _doc_gdscript_basics_static_functions:
1565+
15601566
Static functions
15611567
~~~~~~~~~~~~~~~~
15621568

‎tutorials/scripting/gdscript/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ GDScript
1616
gdscript_styleguide
1717
static_typing
1818
warning_system
19+
warnings/index
1920
gdscript_format_string
2021

2122
.. seealso::

‎tutorials/scripting/gdscript/warnings/assert_always_false.rst

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
ASSERT_ALWAYS_FALSE
2+
=======================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
Assert statement will raise an error because the expression is always false.
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Assert Always False<class_ProjectSettings_property_debug/gdscript/warnings/assert_always_false>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
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.
17+
18+
If ``assert()`` is passed something guaranteed to be false in a boolean context, then the ``assert()`` call will always stop the project.
19+
20+
.. code-block::
21+
22+
# Zero always evaluates to false.
23+
assert(0, "Zero is false in a boolean context")
24+
25+
# Likewise, an empty string always evaluates to false.
26+
assert("", "An empty string is false in a boolean context")
27+
28+
.. note::
29+
30+
Godot will *not* raise this warning if a literal false boolean is passed:
31+
32+
.. code-block::
33+
34+
# Despite false being passed, this won't raise ASSERT_ALWAYS_FALSE.
35+
assert(false, "False is false")
36+
37+
This is because ``assert(false)`` calls are often used in development to forcibly halt program execution and avoid strange errors later on.
38+
39+
See `GH-58087 <https://github.com/godotengine/godot/issues/58087>`_ for more information.
40+
41+
How to fix this warning
42+
-----------------------
43+
44+
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>`.
45+
46+
47+

‎tutorials/scripting/gdscript/warnings/assert_always_true.rst

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
ASSERT_ALWAYS_TRUE
2+
======================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
Assert statement is redundant because the expression is always true.
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Assert Always True<class_ProjectSettings_property_debug/gdscript/warnings/assert_always_true>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
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.
17+
18+
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.
19+
20+
.. code-block::
21+
22+
# The boolean true will always be true, so this assert will never stop
23+
# the program.
24+
assert(true, "True is false, somehow?")
25+
26+
# Likewise, 3 will never be equal to 4, so this assert will never stop
27+
# the program.
28+
assert(3 != 4, "3 is equal to 4")
29+
30+
How to fix this warning
31+
-----------------------
32+
33+
Remove the ``assert()`` statement from your code.
34+
35+
36+

‎tutorials/scripting/gdscript/warnings/confusable_capture_reassignment.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
CONFUSABLE_CAPTURE_REASSIGNMENT
2+
===================================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
Reassigning lambda capture does not modify the outer local variable "my_var".
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Confusable Capture Reassignment<class_ProjectSettings_property_debug/gdscript/warnings/confusable_capture_reassignment>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
TODO
17+
18+
19+
How to fix this warning
20+
-----------------------
21+
22+
TODO
23+
24+
25+

‎tutorials/scripting/gdscript/warnings/confusable_identifier.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
CONFUSABLE_IDENTIFIER
2+
=========================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
The identifier "my_vаr" has misleading characters and might be confused with something else.
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Confusable Identifier<class_ProjectSettings_property_debug/gdscript/warnings/confusable_identifier>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
Some scripts such as Cyrillic have characters that look like Latin (such as English, Spanish, etc.) characters, but are actually different.
17+
18+
.. code-block::
19+
20+
var engine_nаme = "Godot"
21+
print(engine_name)
22+
23+
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).
24+
25+
How to fix this warning
26+
-----------------------
27+
28+
Avoid using Cyrillic or other scripts' characters that are visually similar to Latin ones. A good rule of thumb is to prefer the Latin alphabet for program identifiers.
29+
30+
31+

‎tutorials/scripting/gdscript/warnings/confusable_local_declaration.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
CONFUSABLE_LOCAL_DECLARATION
2+
================================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
The variable "my_param" is declared below in the parent block.
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Confusable Local Declaration<class_ProjectSettings_property_debug/gdscript/warnings/confusable_local_declaration>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
TODO
17+
18+
19+
How to fix this warning
20+
-----------------------
21+
22+
TODO
23+
24+
25+

‎tutorials/scripting/gdscript/warnings/confusable_local_usage.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
CONFUSABLE_LOCAL_USAGE
2+
==========================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
The identifier "my_var" will be shadowed below in the block.
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Confusable Local Usage<class_ProjectSettings_property_debug/gdscript/warnings/confusable_local_usage>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
TODO
17+
18+
19+
How to fix this warning
20+
-----------------------
21+
22+
TODO
23+
24+
25+

‎tutorials/scripting/gdscript/warnings/deprecated_keyword.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
DEPRECATED_KEYWORD
2+
======================
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
The "..." keyword is deprecated and will be removed in a future release. Please replace it with "...".
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Deprecated Keyword<class_ProjectSettings_property_debug/gdscript/warnings/deprecated_keyword>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
There are currently no deprecated keywords in GDScript; as such, this warning should never appear.
17+
18+
19+
How to fix this warning
20+
-----------------------
21+
22+
Follow instructions on the Godot Docs for how to use the alternative keyword.
23+
24+
25+

‎tutorials/scripting/gdscript/warnings/empty_file.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
EMPTY_FILE
2+
==============
3+
4+
The warning message is:
5+
6+
.. code-block:: none
7+
8+
Empty script file.
9+
10+
The default warning level for this warning is **Warn**.
11+
To modify it, set :ref:`Project Settings > Debug > GDScript > Warnings > Empty File<class_ProjectSettings_property_debug/gdscript/warnings/empty_file>`.
12+
13+
When this warning occurs
14+
------------------------
15+
16+
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.
17+
18+
How to fix this warning
19+
-----------------------
20+
21+
Add code to the ``.gd`` file or delete it.
22+
23+
24+

0 commit comments

Comments
 (0)