Added annotations to GDScript

[juan-garcia-m]

Annotations for GDScript!

Annotations can be used with the following syntax examples:

@annotation_name
@annotation_name optional_parameter_1 optional_parameter_n

• At mark (@) to start the annotation
• annotation_name: a valid GDScript identifer (keywords can be enable as
  valid annotation name by setting allow_keywords to true)
• 0 or more parameters separated by spaces. Valid parameters are GDScript
  constants, identifiers or build-in types.

What are annotations used for?

Annotations by themselves are pretty much useless. However it can be a
great way to provide meta information to external tools processing the
GDscript source files. The example bellow should be self explained for
possible uses of annotations in GDScript and external tools like doc
autogeneration.

Example (GDScript code bellow):

# Annotations can be used in the top level
@vendor "com.example"
@module "my_game_lib"
@package "hello"

@author "John Doe"
@description "An example class for GDScript annotations."
@description "Can have multiline descriptions."

extends Node

@private
@type string
var message = "hello, world!"

@private
@type Vector2
var values = Vector2(1, 2)

func _ready():
	example()

@public
@param int arg_value "Value added to the internal number"
@return_type void
@description "Prints a message and a number"
func example(arg_value):
	#Annotations can also be used in local variables (only)

	@type int
	var x = values.x

	@type int
	var y = values.y

	print(message)
	print(str(x + y + arg_value))

[leonkrause]

Why not just use comments? E.g. doxygen uses ## to start a documentation block. I don't see the need to make this a part of the GDScript implementation

[bojidar-bg]

Overlaps with #8217

[juan-garcia-m]

@eska014 I was doing some test with annotations in comments, like the JavaScript way.
However, this kind of annotations are harder to parse and are not enforced to use a correct syntax in the editor. Also with this PR annotations are syntax highlighted already.

I am writing a set of tools for Godot in GDScript itself, and annotations will be of great help for those. Some example of those tools are:

• A maven/gradle similar build tool to manage dependencies (this is great for not having to commit external addons for libraries)
• A library publishing plugin for the above
• Documentation generator in HTML format

This is just the initial state for annotations, and they have to be processed externally. But with new versions more interesting tools like attaching annotations processors scripts per scene or project could be possible.

I am sure that the community will come with more and more interesting ideas.

[neikeq]

A few comments not related to this PR but your code example:

• There are plans to add optional typing to GDScript, so ideally you would use that instead of @type.
• I wouldn't use visibility attributes. Just follow the convention and treat anything that begins with underscore as private.
• I also think documentation is better if generated from comments.

[karroffel]

This can be done using comments, like doxygen does. doxygen requires the comments to be in a certain context too, so it can be resolved in an external tool.

If this would add information to the AST and a way to query nodes for annotations or a way to get all nodes that have a certain annotation, then I think this would be a really really cool PR, but this implementation is only a different kind of comment at a limited location in source.

If this stays like it is now and doesn't add those AST/Reflection features then I don't think this should be merged

[juan-garcia-m]

@karroffel I will add callbacks for annotations.
I can add a project property with an script to process the annotations.
Not sure how to call this. Ideally each script on save should call the annotation processor on itself. Also it should be a way to call scripts by paths, so it can be scripted for build scripts using GDScript itself.
Full AST is imposible now. Something like this example:

func _on_func(annotation_name, annotation_params_array, func_name. func_params, is_static)

In the future we could also expose the AST to GDScript like:

func _on_receive_ast(ast)

[juan-garcia-m]

@neikeq the code example is only to show some obvious ways to use the annotations, I am sure it will be better ways to do documentation. Please note that the interesting things that can be done are not doc generation, but serialization bindings, validation, automatic code generation, etc.

[akien-mga]

Godot's development design is to only implement stuff that is generic enough to serve a big share of the users. This allows to avoid having code for corner case all over the place, making the (already huge) engine code harder to maintain.

As such, and as you discussed it with @karroffel on IRC already, I don't see a point in merging this for now as it serves no purpose within the engine, but is only an added convenience for external tooling that could rely on special comment syntax instead.

See also https://github.com/godotengine/godot/blob/master/CONTRIBUTING.md#contributing-pull-requests for tips on a better workflow to get things discussed and pre-approved before spending time implementing them.

I know you have some more advanced ideas about what to do with annotations than what is implemented here, and they do sound quite interesting, so I would propose that you open an issue about it so that it can be discussed together with other devs, and then implemented in a way that will satisfy everyone's needs.

[juan-garcia-m]

Hi guys.
Thank you for the feedback.