From 71e4e2ce33eba7953e1022be089a18f085826fc3 Mon Sep 17 00:00:00 2001 From: Allen Pestaluky Date: Mon, 22 Apr 2024 12:33:43 -0400 Subject: [PATCH] Improved description of annotations Removes an unnecessary and potentially confusing comparison of annotations to keywords and generally improves wording in the GDScript Basics tutorial. A new page to the Contributing section has been added for scripting development guidelines. This new page hosts suggestions on when annotations should be implemented in GDScript. --- .../development/core_and_modules/index.rst | 1 + .../scripting_development.rst | 38 +++++++++++++++++++ .../scripting/gdscript/gdscript_basics.rst | 12 +++--- 3 files changed, 45 insertions(+), 6 deletions(-) create mode 100644 contributing/development/core_and_modules/scripting_development.rst diff --git a/contributing/development/core_and_modules/index.rst b/contributing/development/core_and_modules/index.rst index a97df05f2a04..336cdb55502e 100644 --- a/contributing/development/core_and_modules/index.rst +++ b/contributing/development/core_and_modules/index.rst @@ -23,6 +23,7 @@ This section covers the basics that you will encounter in (almost) every source inheritance_class_tree internal_rendering_architecture 2d_coordinate_systems + scripting_development Extending Godot by modifying its source code -------------------------------------------- diff --git a/contributing/development/core_and_modules/scripting_development.rst b/contributing/development/core_and_modules/scripting_development.rst new file mode 100644 index 000000000000..4aaa13f46a8e --- /dev/null +++ b/contributing/development/core_and_modules/scripting_development.rst @@ -0,0 +1,38 @@ +.. _doc_scripting_development: + +Scripting development +===================== + +GDScript +-------- + +Annotation guidelines +~~~~~~~~~~~~~~~~~~~~~ + +.. + This description intentionally avoids mention of implementation and + compilation details because these are often inconsistent between annotations + +Create annotations for modifiers that act on the script or its code. +Addionally, create annotations for behaviour 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. + +Do not create annotations for general programming language features. + +:: + + # Affects how the editor treats this script. + @icon("res://path/to/class/icon.svg") + + # Affects how the engine interacts this script. + @onready var character_name = $Label + + # static is a general programming language feature. + static var num_players = 2 + +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 65588bf0a1f5..e07d9ae55365 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -446,13 +446,13 @@ GDScript also supports :ref:`format strings `. Annotations ~~~~~~~~~~~ -There are some special tokens in GDScript that act like keywords but are not, -they are *annotations* instead. Every annotation start with the ``@`` character -and is specified by a name. A detailed description and example for each annotation -can be found inside the :ref:`GDScript class reference `. +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 affect how the script is treated by external tools and usually don't -change the behavior. +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 +:ref:`GDScript class reference `. For instance, you can use it to export a value to the editor::