Merge pull request #9188 from allenwp/annotation-improvements

Improve description of annotations

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
 --------------------------------------------

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 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.
+
+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.

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -450,13 +450,13 @@ GDScript also supports :ref:`format strings <doc_gdscript_printf>`.
 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 <class_@GDScript>`.
+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 <class_@GDScript>`.
 
 For instance, you can use it to export a value to the editor::