Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added annotations to GDScript #9469

Closed
wants to merge 3 commits into from
Closed

Added annotations to GDScript #9469

wants to merge 3 commits into from

Conversation

juan-garcia-m
Copy link

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

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

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 "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
Copy link
Contributor

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
Copy link
Contributor

Overlaps with #8217

@juan-garcia-m
Copy link
Author

juan-garcia-m commented Jul 2, 2017

@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
Copy link
Contributor

neikeq commented Jul 2, 2017

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
Copy link
Contributor

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
Copy link
Author

@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
Copy link
Author

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

* Create AnnotationNode struct
* Added annotation name to AnnotationNode
* Made allow_keywords constant (might be removed)

TODO: Add AnnotationNode struct to the AST (how?)
TODO: Add annotation parameters to AnnotationNode (creating Variant Array?)
TODO: Make the AST visible from GDScript
@akien-mga
Copy link
Member

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
Copy link
Author

Hi guys.
Thank you for the feedback.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants