GDScript: Update annotation description and development guidelines

Author: dalexeev

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.

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -449,9 +449,9 @@ GDScript also supports :ref:`format strings <doc_gdscript_printf>`.
 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