Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

GDScript documentation comments

In GDScript, comments can be used to document your code and add descriptions to the members of a script. There are two differences between a normal comment and a documentation comment. Firstly, a documentation comment should start with double hash symbols ##. Secondly, it must immediately precede a script member, or for script descriptions, be placed at the top of the script. If an exported variable is documented, its description is used as a tooltip in the editor. This documentation can be generated as XML files by the editor.

Documenting a script

Comments documenting a script must come before any member documentation. A suggested format for script documentation can be divided into three parts.

• A brief description of the script.

• Descripción detallada.

• Tutorials and deprecated/experimental marks.

To separate these from each other, the documentation comments use special tags. The tag must be at the beginning of a line (ignoring preceding white space) and must have the format @, followed by the keyword.

Tags

Brief description	No tag. Lives at the very beginning of the documentation section.
Descripción	No tag. Use one blank line to separate the description from the brief.
Tutorial	@tutorial: @tutorial(The Title Here):
Deprecated	@deprecated
Experimental	@experimental

For example:

extends Node2D
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
##
## @tutorial:            https://the/tutorial1/url.com
## @tutorial(Tutorial2): https://the/tutorial2/url.com
## @experimental

Advertencia

If there is any space in between the tag name and colon, for example @tutorial  :, it won't be treated as a valid tag and will be ignored.

Nota

When the description spans multiple lines, the preceding and trailing white spaces will be stripped and joined with a single space. To preserve the line break use [br]. See also BBCode and class reference below.

Documenting script members

Members that are applicable for documentation:

• Inner class

• Constant

• Función

• Señal

• Variable

• Enum

• Valor de enumeración

Documentation of a script member must immediately precede the member or its annotations if it has any. The description can have more than one line but every line must start with the double hash symbol ## to be considered as part of the documentation.

Tags

Descripción	No tag.
Deprecated	@deprecated
Experimental	@experimental

For example:

## The description of the variable.
## @deprecated
var my_var

Alternatively, you can use inline documentation comments:

enum MyEnum { ## My enum.
    VALUE_A = 0, ## Value A.
    VALUE_B = 1, ## Value B.
}

const MY_CONST = 1 ## My constant.

var my_var ## My variable.

signal my_signal ## My signal.

func my_func(): ## My func.
    pass

class MyClass: ## My class.
    pass

The script documentation will update in the editor help window every time the script is updated. If any member variable or function name starts with an underscore, it will be treated as private. It will not appear in the documentation and will be ignored in the help window.

Complete script example

extends Node2D
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
##
## @tutorial:            https://the/tutorial1/url.com
## @tutorial(Tutorial2): https://the/tutorial2/url.com
## @experimental

## The description of a constant.
const GRAVITY = 9.8

## The description of a signal.
signal my_signal

## This is a description of the below enum.
enum Direction {
    ## Direction up.
    UP = 0,
    ## Direction down.
    DOWN = 1,
    ## Direction left.
    LEFT = 2,
    ## Direction right.
    RIGHT = 3,
}

## The description of the variable v1.
var v1

## This is a multiline description of the variable v2.[br]
## The type information below will be extracted for the documentation.
var v2: int

## If the member has any annotation, the annotation should
## immediately precede it.
@export
var v3 := some_func()


## As the following function is documented, even though its name starts with
## an underscore, it will appear in the help window.
func _fn(p1: int, p2: String) -> int:
    return 0


# The below function isn't documented and its name starts with an underscore
# so it will treated as private and will not be shown in the help window.
func _internal() -> void:
    pass


## Documenting an inner class.
##
## The same rules apply here. The documentation must
## immediately precede the class definition.
##
## @tutorial: https://the/tutorial/url.com
## @experimental
class Inner:

    ## Inner class variable v4.
    var v4


    ## Inner class function fn.
    func fn(): pass

@deprecated and @experimental tags

You can mark a class or any of its members as deprecated or experimental. This will add the corresponding indicator in the built-in documentation viewer. This can be especially useful for plugin and library creators.

• Deprecated marks a non-recommended API that is subject to removal or incompatible change in a future major release. Usually the API is kept for backwards compatibility.

• Experimental marks a new unstable API that may be changed or removed in the current major branch. Using this API is not recommended in production code.

Nota

While technically you can use both @deprecated and @experimental tags on the same class/member, this is not recommended as it is against common conventions.

BBCode and class reference

The editor help window which renders the documentation supports bbcode. As a result it's possible to align and format the documentation. Color texts, images, fonts, tables, URLs, animation effects, etc. can be added with the bbcode.

La referencia de clases de Godot soporta etiquetas del estilo BBCode. Estas pueden agregar un formato al texto que también se puede usar en la documentación. Ver también class reference bbcode.

Whenever you link to a member of another class, you need to specify the class name. For links to the same class, the class name is optional and can be omitted.

Here's the list of available tags:

Tag and Description	Ejemplo	Resultado
[Class] Link to class	Mueve el [Sprite2D].	Move the Sprite2D.
[annotation Class.name] Link to annotation	See [annotation @GDScript.@export].	See @GDScript.@export.
[constant Class.name] Vínculo a constante	See [constant @GlobalScope.KEY_F1].	See @GlobalScope.KEY_F1.
[enum Class.name] Link to enum	See [enum Mesh.ArrayType].	See Mesh.ArrayType.
[method Class.name] Link to method	Llama a [method Node3D.hide].	Call Node3D.hide().
[member Class.name] Vínculo a miembro	Obtén [member Node2D.scale].	Get Node2D.scale.
[signal Class.name] Link to signal	Emite [signal Node.renamed].	Emit Node.renamed.
[theme_item Class.name] Link to theme item	See [theme_item Label.font].	See Label.font.
[param name] Formats a parameter name (as code)	Takes [param size] for the size.	Takes size for the size.
[br] Line break	Line 1.[br] Line 2.	Line 1. Line 2.
[b] [/b] Negrita	Un texto en [b]negrita[/b].	Algo de texto en negrita.
[i] [/i] Cursiva	Un texto en [i]itálica[/i].	Algo de texto en cursiva.
[kbd] [/kbd] Atajo del teclado/ratón	Una tecla [kbd]Ctrl + C[/kbd].	Alguna tecla Ctrl + C.
[code] [/code] Monospace	Un texto [code]monoespaciado[/code].	Algo de texto monospace.
[codeblock] [/codeblock] Bloque pre-formateado con múltiples líneas	Ver a continuación.	Ver a continuación.

Nota

1. Currently only @GDScript has annotations.

2. [code] disables BBCode until the parser encounters [/code].

3. [codeblock] disables BBCode until the parser encounters [/codeblock].

Advertencia

Usa [codeblock] para bloques de código preformateados. Dentro de [codeblock], siempre utiliza cuatro espacios para la indentación (el analizador eliminará las tabulaciones).

## Do something for this plugin. Before using the method
## you first have to [method initialize] [MyPlugin].[br]
## [color=yellow]Warning:[/color] Always [method clean] after use.[br]
## Usage:
## [codeblock]
## func _ready():
##     the_plugin.initialize()
##     the_plugin.do_something()
##     the_plugin.clean()
## [/codeblock]
func do_something():
    pass