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.
Detailed description.
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.
Documenting script members¶
Members that are applicable for documentation:
Inner class
Constant
Function
Signal
Variable
Enum
Enum value
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¶
Description |
No tag. |
Deprecated |
|
Experimental |
|
For example:
## The description of the variable.
## @deprecated
var my_var
Variables, constants, signals, and enum values support inline documentation comments. Note that inline comments do not support tags.
var my_var ## My variable.
const MY_CONST = 1 ## My constant.
signal my_signal ## My signal.
enum Direction {
UP = 0, ## Direction up.
DOWN = 1, ## Direction down.
LEFT = 2, ## Direction left.
RIGHT = 3, ## Direction right.
}
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 a constant.
const GRAVITY = 9.8
## 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
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.
Godot's class reference supports BBCode-like tags. They add nice formatting to the text which could also be used in the documentation. See also 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 |
Example |
Result |
---|---|---|
[Class] Link to class
|
|
Move the Sprite2D. |
[annotation Class.name] Link to annotation
|
|
See @GDScript.@export. |
[constant Class.name] Link to constant
|
|
See @GlobalScope.KEY_F1. |
[enum Class.name] Link to enum
|
|
See Mesh.ArrayType. |
[method Class.name] Link to method
|
|
Call Node3D.hide(). |
[member Class.name] Link to member
|
|
Get Node2D.scale. |
[signal Class.name] Link to signal
|
|
Emit Node.renamed. |
[theme_item Class.name] Link to theme item
|
|
See Label.font. |
[param name] Formats a parameter name (as code)
|
|
Takes |
[br] Line break
|
Line 1.[br] Line 2. |
Line 1.
Line 2.
|
[b] [/b] Bold
|
|
Some bold text. |
[i] [/i] Italic
|
|
Some italic text. |
[kbd] [/kbd] Keyboard/mouse shortcut
|
|
Some Ctrl + C key. |
[code] [/code] Monospace
|
|
Some |
[codeblock] [/codeblock] Multiline preformatted block
|
See below. |
See below. |
Note
Currently only @GDScript has annotations.
[code]
disables BBCode until the parser encounters[/code]
.[codeblock]
disables BBCode until the parser encounters[/codeblock]
.
Warning
Use [codeblock]
for pre-formatted code blocks. Inside [codeblock]
,
always use four spaces for indentation (the parser will delete tabs).
## 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