diff --git a/contributing/development/core_and_modules/scripting_development.rst b/contributing/development/core_and_modules/scripting_development.rst index 865189e2604..1a966dc84af 100644 --- a/contributing/development/core_and_modules/scripting_development.rst +++ b/contributing/development/core_and_modules/scripting_development.rst @@ -9,30 +9,57 @@ GDScript Annotation guidelines ~~~~~~~~~~~~~~~~~~~~~ -.. - This description intentionally avoids mention of implementation and - compilation details because these are often inconsistent between annotations +In Godot 3 we had a lot of keywords (including ``tool``, ``export``, ``onready``). +This had the following disadvantages: -Create annotations for modifiers that act on the script or its code. -Additionally, create annotations for behavior that is specific to the Godot -engine and editor; if the primary purpose is to affect the way that the engine -or editor treats or interacts with the script, implement the token as an -annotation. +- Overcomplication of the language grammar. +- Possible conflicts with user identifiers. +- Need to touch the parser in a major way to add a new keyword. -Do not create annotations for general programming language features. +So in Godot 4 we introduced the concept of annotations. An annotation is a modifier +(an attribute, a marker) that can be applied to an entire script, a declaration, +a statement, or a location in the source code. Annotations can optionally take +additional arguments, listed in parentheses. Annotation arguments must be constant +expressions or string literals (in a few special cases where the argument value +must be resolved in the parser rather than in the analyzer). -:: +Currently, an annotation target can be a combination of the following +``GDScriptParser::AnnotationInfo::TargetKind`` flags: - # Affects how the editor treats this script. - @icon("res://path/to/class/icon.svg") - - # Affects how the engine interacts with this script. - @onready var character_name = $Label ++-----------------+----------------------------------------------+-----------------------------+ +| **Target Kind** | **Description** | **Example** | ++=================+==============================================+=============================+ +| ``SCRIPT`` | The entire script. | ``@tool`` | ++-----------------+----------------------------------------------+-----------------------------+ +| ``CLASS`` | A class (both the outermost and inner ones). | ``@abstract`` | ++-----------------+----------------------------------------------+-----------------------------+ +| | ``VARIABLE`` | Other types of class members. | ``@export`` | +| | ``CONSTANT`` | | | +| | ``SIGNAL`` | | | +| | ``FUNCTION`` | | | ++-----------------+----------------------------------------------+-----------------------------+ +| ``STATEMENT`` | Statements inside a function. | ``@warning_ignore`` | ++-----------------+----------------------------------------------+-----------------------------+ +| ``STANDALONE`` | Some place inside a class or a line | | ``@export_category`` | +| | in the source code. | | ``@warning_ignore_start`` | +| | | | +| | 1. Class pseudo-members. | | +| | 2. Markers for the start and end | | +| | of a warning-ignoring region. | | ++-----------------+----------------------------------------------+-----------------------------+ - # static is a general programming language feature. - static var num_players = 2 +**When to use a keyword and when an annotation to implement a new feature?** -For historical reasons, some existing annotations and keywords do not strictly -follow these guidelines. Choosing between implementing a feature as an -annotation or as a language keyword is a nuanced decision that should be made -through discussion with other GDScript developers. +- **General rule:** Do not use keywords unless they are required by the language grammar + and the parser. Do not use annotations for independent syntactic units. +- Use keywords for class member declarators (``var``, ``const``, ``func``). +- Use annotations for class member modifiers (``@export``, ``@onready``, ``@abstract``). +- Use keywords for operators within expressions (``and``), for delimiters in statements + (``in``, ``when``) and declarations (``extends``). + +.. note:: + + For historical reasons, some existing annotations and keywords do not strictly + follow these guidelines. Choosing between implementing a feature as an annotation + or as a language keyword is a nuanced decision that should be made through discussion + with other GDScript developers. diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 0749a0111b4..f860b8cb857 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -449,9 +449,9 @@ GDScript also supports :ref:`format strings `. Annotations ----------- -Annotations are special tokens in GDScript that act as modifiers to a script or -its code and may affect how the script is treated by the Godot engine or -editor. +Annotations are special tokens in GDScript that act as modifiers to an entire script, +a declaration, a statement, or a location in the source code. Annotations may affect +how the script is treated by the Godot editor and the GDScript compiler. Every annotation starts with the ``@`` character and is specified by a name. A detailed description and example for each annotation can be found inside the