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.