Improve description of annotations

[allenwp]

This change uses wording from discussions in the RocketChat GDscript channel.

[AThousandShips]

I still think the specifics of what annotations are isn't relevant to this article, I don't think it should even mention keywords because it's irrelevant

[allenwp]

I’m intentionally leaving this as a draft PR until after the Tuesday GDScript meeting, in case that meeting highlights any other ways annotations could be described in documentation.

[dalexeev]

I don't agree that the difference between annotations and keywords is how the script is compiled. In fact, annotations affect the script behavior and the bytecode generated (for example, @onready moves member variable initialization to @implicit_ready() function). But in any case, these are unnecessary technical details.

I think annotations in GDScript are not much different from keywords. Annotations are not just metadata like attributes in PHP and not a clear language feature like decorators in Python.

Differences between annotations and keywords:

1. Adding a new annotation is guaranteed not to conflict with any identifiers.
2. Adding a new annotation will likely require fewer changes to the parser than adding a keyword.
3. The presence of annotations reduces the number of keywords. This is especially suitable for modifiers on declarations ("annotate" in the sense of "precede"), since modifiers are not used on their own. The only exception is static.

[nlupugla]

Is static really the only exception? Wouldn't extends and perhaps class_name also be considered modifiers?

If not for those counterexamples, it would be tempting to think of keywords as nouns and annotations as adjectives.

[nlupugla]

Thanks for starting on this allenwp!

I'm kind of wondering whether a change like this would be better suited for the "contributing" section of the docs. The user doesn't really care whether static is a keyword or an annotation and why, they just want to know what to type to make their function static. On the other hand, when contributing to GDScript, you'd want some guidelines as to whether to make your new feature of keyword or annotation.

[dalexeev]

Is static really the only exception? Wouldn't extends and perhaps class_name also be considered modifiers?

class_name declares a global class identifier, just classes in GDScript can be unnamed. If class_name is a modifier, then class is too, as well as var, const, func, etc.

extends serves as a separator between the class identifier and the base class name/path. Like in separates the iterable expression from the iterator variable identifier/type in for loop (here token in has a different meaning, not the content test operator). And like when separates the guard expression from the pattern list in match. Also, because class_name is optional, extends can act on its own, so it's not a modifier.

In principle, any keyword could be an annotation (and then you could do something like @var var = 1). But it would be awkward to type. Another approach: keywords are used more often than annotations, especially in function bodies (which is why I would prefer to have let rather than @onready var).

[allenwp]

I'm kind of wondering whether a change like this would be better suited for the "contributing" section of the docs.

💯 Yep, a new Contributing page should be added with guidelines that go into detail on keywords vs annotations.

Maybe I could include that new page in this PR, but I feel I am not the person to write it, as the nuance goes beyond my experience and understanding...

[allenwp]

Actually, maybe I can take stab at this… Here is a thought on how a Contributing section could be written on this subject. It would pair nicely with this current PR draft for the user-facing documentation:

Keywords vs Annotations

If the primary purpose is to affect the way that the engine, editor, or external tools treat or interact with the script, it should be implemented as an annotation. Otherwise, it should be implemented as a keyword.

Edit: I've pushed a new page to the Contributing section of the docs that adds some details on annotations vs. keywords. Please let me know if I've done this correctly, as this is my first time making this sort of change.

[allenwp]

One important note that was brought up during the meeting was that Contributing guidelines should be written based on what we want future tokens to be implemented as, not based on describing all existing annotations and keywords perfectly.

[nlupugla]

An alternative to godot-specific vs general programming is whether the token is more important at run time or compile time. Or maybe another way to say it would be, whether the token operates within the code or on the code itself.

For example, one can think of @onready as acting on the source code (although that's not how it's implemented): creating a _ready function if it doesn't exist and performing the assignment inside it.

Similarly, you can think of @export as modifying the source code to add boilerplate to the _set and _get methods of the script (although again, that is not how it is actually implemented).

In contrast, keywords like func or await don't really "act on the source code" in the same way.

This is also maybe a more helpful guideline for new keywords/annotations going forward. Whereas the distinction between game/Godot-specific and general programming can be fuzzy, I think the distinction between run time/compile time is more clear and might have technical implications about how the feature is implemented. For example, one could imagine designing the GDScript compiler/VM in such a way that all annotations are resolved before non-annotations. This would essentially make annotations an avenue for metaprogramming (e.g. @serializable, @observable, @evaluate(PI / 4)) whereas keywords would be reserved for core language features (e.g. Trait, Interface, maybe, readonly).

[allenwp]

An alternative to godot-specific vs general programming is whether the token is more important at run time or compile time. Or maybe another way to say it would be, whether the token operates within the code or on the code itself.

I think there is some promise with the concept of "annotations operate on the script's code" (as in, the annotations are not considered the "code of the script". I think this is a little different than the historical/previous definitions of GDScript annotations, but again this could be a good thing.

The wording of "the token is more important at runtime" might be confusing to some people, as I interpreted that to mean that annotations like @tool and @export are important at runtime because they change how (existing) code behaves at runtime, whereas access modifier keywords are a traditional compile-time (not runtime) token in pre-compiled languages.

I will try to make some time in the next week or two to write out a new draft with this sort of wording instead, so we can compare it.

[allenwp]

I just pushed a commit that reworks some of the PR. I think this basically the best I can do with annotation documentation for users and contributors based on the comments and discussion that I've seen in RocketChat, the GDScript meeting, and here in this PR. The line I added was:

Create annotations for modifiers that act on the script or its code.

Unfortunately, I don't entirely believe that this new documentation actually helps all that much in guiding whether abstract should be implemented as an annotation or as a keyword. The way I would interpret it is that abstract should be implemented as an annotation because permission modifiers are "modifiers that act on the script's code". It still seems a little vague to me.

These new changes remove the suggestion from @akien-mga:

So I think I like the proposal that annotations are used for engine specific behavior, and keywords are for purely language specific modifiers, which could be used if GDScript was theoretically spinned to a Godot-agnostic language (it won't, but it can be a way to reason about it).

With this new approach, some language features that act on the code, such as metaprogramming, would be implemented as annotations instead of keywords.

[AThousandShips]

Suggested change

	Addionally, create annotations for behaviour that is specific to the Godot
	Addionally, create annotations for behavior that is specific to the Godot

[vnen]

I unmarked this as resolved since the PR still have the previous word.

[allenwp]

In yesterday's GDScript meeting, the decision was made to implemented abstract as a keyword, rather than an annotation. This is somewhat in line with with the previous idea of "Create keywords for modifiers that are, theoretically, equally useful in contexts outside of Godot.". Instead of bringing back this specific wording into the documentation, I've rewrote it slightly. I think this PR is now ready for formal review and merge, so I'm taking it out of draft.

[vnen]

I believe the description of annotations is a good fit for what has been discussed with the GDScript team and it's an improvement of what was there before.

[mhilbrunner]

Merged. Thanks! Good idea to document the results of this discussion. :)