Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Comentários de documentação do GDScript

No GDScript, comentários podem ser usados para documentar seu código e adicionar descrições aos membros de um script. Existem duas diferenças entre um comentário normal e um comentário de documentação. Primeiramente, um comentário de documentação deve começar com símbolos de cerquilha duplos ##. Em segundo lugar, ele deve preceder imediatamente um membro do script ou, para descrições do script, ser colocado no topo do script. Se uma variável exportada for documentada, sua descrição será usada como uma dica de ferramenta (tooltip) no editor. Essa documentação pode ser gerada como arquivos XML pelo editor.

Documentando um script

Comentários que documentam um script devem vir antes de qualquer documentação de membro. Um formato sugerido para a documentação do script pode ser dividido em três partes.

Uma breve descrição do script.
Descrição detalhada.
Tutoriais e marcações de depreciação/experimentação.

Para separar essas partes umas das outras, os comentários de documentação usam tags especiais. A tag deve estar no início de uma linha (ignorando espaços em branco precedentes) e deve ter o formato @, seguido pela palavra-chave.

Tags

Breve descrição	Sem tag. Fica no início absoluto da seção de documentação.
Descrição	Sem decorator(especificador). Use uma linha em branco para separar entre a descrição e o resumo.
Tutorial	`@tutorial: https://example.com` `@tutorial(O Título Aqui): https://example.com`
Depreciado	`@deprecated` `@deprecated: Use [AnotherClass] em seu lugar.`
Experimental	`@experimental` `@experimental: Esta classe é instável.`

Por exemplo:

class_name MyClass
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://example.com/tutorial_1
## @tutorial(Tutorial 2): https://example.com/tutorial_2
## @experimental

Aviso

Se houver qualquer espaço entre o nome da tag e os dois-pontos, por exemplo @tutorial :, ela não será tratada como uma tag válida e será ignorada.

Nota

Quando a descrição abrange várias linhas, os espaços em branco no início e no fim serão removidos e as linhas serão unidas por um único espaço. Para preservar a quebra de linha, use [br]. Veja também BBCode and class reference abaixo.

Documentando membros do script

Membros que podem ser documentados:

Sinal
Enum
Valor de enumeração
Constante
Variável
Função
Classe interna (Inner class)

A documentação de um membro do script deve preceder imediatamente o membro ou suas anotações, se houver. A descrição pode ter mais de uma linha, mas cada linha deve começar com o símbolo de cerquilha duplo ## para ser considerada parte da documentação.

Tags

Descrição	Sem tag.
Depreciado	`@deprecated` `@deprecated: Use [member another] em seu lugar.`
Experimental	`@experimental` `@experimental: Este método está incompleto.`

Por exemplo:

## The description of the variable.
## @deprecated: Use [member other_var] instead.
var my_var

Alternativamente, você pode usar comentários de documentação em linha(inline):

signal my_signal ## My signal.

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.


func my_func(): ## My func.
    pass


class MyClass: ## My class.
    pass

A documentação do script será atualizada na janela de ajuda do editor sempre que o script for atualizado. Se qualquer variável de membro ou nome de função começar com um sublinhado, ela será tratada como privada. Ela não aparecerá na documentação e será ignorada na janela de ajuda.

Exemplo de script completo

class_name MyClass
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://example.com/tutorial_1
## @tutorial(Tutorial 2): https://example.com/tutorial_2
## @experimental

## 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://example.com/tutorial
## @experimental
class Inner:

    ## Inner class variable v4.
    var v4


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

Tags `@deprecated` e `@experimental`

Você pode marcar uma classe ou qualquer um de seus membros como depreciado (deprecated) ou experimental. Isso adicionará o indicador correspondente no visualizador de documentação integrado. Opcionalmente, você pode fornecer uma mensagem curta explicando por que a API não é recomendada. Isso pode ser especialmente útil para criadores de plugins e bibliotecas.

../../../_images/deprecated_and_experimental_tags.webp

Deprecated (Depreciado) marca uma API não recomendada que está sujeita a remoção ou alterações incompatíveis em uma versão principal (major release) futura. Geralmente, a API é mantida para compatibilidade com versões anteriores.
Experimental marca uma nova API instável que pode ser alterada ou removida na ramificação principal atual. O uso desta API não é recomendado em código de produção.

Nota

Embora tecnicamente você possa usar as tags @deprecated e @experimental na mesma classe/membro, isso não é recomendado, pois vai contra as convenções comuns.

BBCode e referência de classe

A referência de classe do Godot suporta tags no estilo BBCode. Elas adicionam uma boa formatação ao texto, que também pode ser usada na documentação. Veja também class reference bbcode. Note que isso é um pouco diferente do RichTextLabel BBCode.

Sempre que você vincular a um membro de outra classe, precisará especificar o nome da classe. Para links para a mesma classe, o nome da classe é opcional e pode ser omitido.

Aqui está a lista de tags disponíveis:

Tag e Descrição	Exemplo	Resultado
`[Class]` Link para classe	`Mova o [Sprite2D].`	Mova o Sprite2D.
`[annotation Classe.nome]` Link para anotação	`Veja [annotation @GDScript.@rpc].`	Veja @GDScript.@rpc.
`[constant Classe.nome]` Link para constante	`Veja [constant Color.RED].`	Veja Color.RED.
`[enum Classe.nome]` Link para enum	`Veja [enum Mesh.ArrayType].`	Veja Mesh.ArrayType.
`[member Classe.nome]` Link para membro (propriedade)	`Obtenha [member Node2D.scale].`	Obtenha Node2D.scale.
`[method Class.name]` Link para método	`Chame [method Node3D.hide].`	Chame Node3D.hide().
`[constructor Class.name]` Link para construtor integrado	`Use [constructor Color.Color].`	Use Color.Color.
`[operator Class.name]` Link para operador integrado	`Use [operator Color.operator *].`	Use Color.operator *.
`[signal Classe.nome]` Link para sinal	`Emita [signal Node.renamed].`	Emita Node.renamed.
`[theme_item Classe.nome]` Link para item de tema	`Veja [theme_item Label.font].`	Veja Label.font.
`[param name]` Nome do parâmetro (como código)	`Recebe [param size] para o tamanho.`	Recebe `size` para o tamanho.
`[br]` Quebra de linha	`Linha 1.[br]` `Linha 2.`	Linha 1. Linha 2.
`[lb]` `[rb]` `[` e `]` respectivamente	`[lb]b[rb]texto[lb]/b[rb]`	[b]texto[/b]
`[b]` `[/b]` Negrito	`Não[/b] chame este método.`	Não chame este método.
`[i]` `[/i]` Itálico	`Retorna a posição [i]global[/i].`	Retorna a posição global.
`[u]` `[/u]` Sublinhado	`[u]Sempre[/u] use este método.`	Always use this method.
`[s]` `[/s]` Tachado	`[s]Informação desatualizada.[/s]`	~~Outdated information.~~
`[color]` `[/color]` Cor	`[color=red]Erro![/color]`	Error!
`[font]` `[/font]` Fonte	`[font=res://mono.ttf]LICENSE[/font]`	LICENSE
`[img]` `[/img]` Imagem	`[img width=32]res://icon.svg[/img]`
`[url]` `[/url]` Hiperlink	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Website
`[center]` `[/center]` Centralização horizontal	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Atalho de teclado/mouse	`Pressione [kbd]Ctrl + C[/kbd].`	Pressione `Ctrl + C`.
`[code]` `[/code]` Fragmento de código inline	`Retorna [code]true[/code].`	Retorna `true`.
`[codeblock]` `[/codeblock]` Bloco de código multilinha	Veja abaixo.	Veja abaixo.

Nota

Atualmente, apenas o @GDScript possui anotações.
[kbd] desativa o BBCode até que o analisador encontre [/kbd].
[code] desativa o BBCode até que o analisador encontre [/code].
[codeblock] desativa o BBCode até que o analisador encontre [/codeblock].

Aviso

Use [codeblock] para blocos de código pré-formatados. Dentro de [codeblock], sempre use quatro espaços para indentação (o analisador removerá os caracteres tab).

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

Por padrão, [codeblock] destaca a sintaxe do GDScript. Você pode alterá-la usando o atributo lang. As opções suportadas atualmente são:

[codeblock lang=text] desativa o destaque de sintaxe;
[codeblock lang=gdscript] destaca a sintaxe do GDScript;
[codeblock lang=csharp] destaca a sintaxe de C# (apenas na versão .NET).

Comentários de documentação do GDScript

Documentando um script

Tags

Documentando membros do script

Tags

Exemplo de script completo

Tags @deprecated e @experimental

BBCode e referência de classe

Tags `@deprecated` e `@experimental`