Commenti di documentazione in GDScript

In GDScript, i commenti possono essere utilizzati per documentare il codice e aggiungere descrizioni ai membri di uno script. Esistono due differenze tra un commento normale e un commento di documentazione. Prima di tutto, un commento di documentazione deve iniziare con due simboli cancelletto ##. Inoltre, deve precedere immediatamente un membro dello script o, per le descrizioni di script, essere posizionato in cima allo script. Se una variabile esportata è documentata, la sua descrizione viene utilizzata come suggerimento nell'editor. Questa documentazione si può generare come file XML dall'editor.

Documentare uno script

I commenti che documentano uno script devono precedere qualsiasi documentazione relativa ai suoi membri. Il formato suggerito per la documentazione di uno script può essere suddiviso in tre parti.

Una breve descrizione dello script.
Una descrizione dettagliata.
Tutorial e note di deprecazione/esperimentale.

Per separarli, i commenti di documentazione utilizzano tag speciali. Il tag deve trovarsi all'inizio di una riga (ignorando gli spazi vuoti precedenti) e deve avere il formato @, seguito dalla parola chiave.

Tag

Breve descrizione	Nessun tag. Si trova all'inizio della sezione di documentazione.
Descrizione	Nessun tag. Usa una riga vuota per separarla dalla descrizione breve.
Tutorial	`@tutorial: https://example.com` `@tutorial(Il titolo qui): https://example.com`
Deprecato	`@deprecated` `@deprecated: Usa invece [AltraClasse].`
Sperimentale	`@experimental` `@experimental: Questa classe non è stabile.`

Per esempio:

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

Avvertimento

Se c'è uno spazio tra il nome del tag e i due punti, ad esempio @tutorial :, non sarà considerato un tag valido e sarà ignorato.

Nota

Quando la descrizione si estende su più righe, gli spazi vuoti precedenti e finali saranno eliminati e uniti da un singolo spazio. Per mantenere l'interruzione di riga, utilizzare [br]. Consultare anche BBCode and class reference in seguito.

Documentare i membri di script

Membri idonei per la documentazione:

Segnale
Enumerazione
Valore di enumerazione
Costante
Variabile
Funzione
Classe interna

La documentazione di un membro di uno script deve precedere immediatamente il membro stesso o le sue annotazioni, se presenti. La descrizione può essere composta da più righe, ma ogni riga deve cominciare con il doppio simbolo cancelletto ## per essere considerata parte della documentazione.

Tag

Descrizione	Nessun tag.
Deprecato	`@deprecated` `@deprecated: Usa invece [member altro].`
Sperimentale	`@experimental` `@experimental: Questo metodo è incompleto.`

Per esempio:

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

In alternativa, è possibile scrivere la documentazione sulla stessa riga:

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

La documentazione dello script verrà aggiornata nella finestra di aiuto dell'editor ogni volta che lo script viene aggiornato. Se il nome di una variabile membro o di una funzione inizia con un trattino basso, sarà considerato privato. Non apparirà nella documentazione e sarà ignorato nella finestra di aiuto.

Esempio completo per uno script

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

Tag `@deprecated` e `@experimental`

È possibile segnare una classe o uno qualsiasi dei suoi membri come deprecati o sperimentali. Questo aggiungerà l'indicatore corrispondente nella vista di documentazione integrata. Facoltativamente, è possibile fornire un breve messaggio che spieghi perché l'API non è consigliata. Questo può essere particolarmente utile per i creatori di estensioni e librerie.

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

Deprecato indica un'API non consigliata che potrebbe essere rimossa o modificata in modo incompatibile in una futura versione principale. Solitamente l'API viene mantenuta per compatibilità con le versioni precedenti.
Sperimentale indica una nuova API instabile che potrebbe essere modificata o rimossa nel ramo principale di sviluppo. L'utilizzo di questa API non è consigliato nel codice di produzione.

Nota

Sebbene tecnicamente sia possibile utilizzare entrambi i tag @deprecated e @experimental sulla stessa classe/membro, ciò non è consigliato in quanto va contro le convenzioni comuni.

BBCode e riferimento di classe

Il riferimento classi di Godot supporta tag simili a BBCode. Aggiungono un'elegante formattazione al testo, la quale si potrebbe utilizzare anche nella documentazione. Consultare anche bbcode per il riferimento classi bbcode. Si noti che è leggermente diverso dal BBCode di RichTextLabel .

Ogni volta che si crea un collegamento a un membro di un'altra classe, è necessario specificarne il nome. Per i collegamenti alla stessa classe, il nome della classe è facoltativo e può essere omesso.

Ecco l'elenco di tag disponibili:

Tag e descrizione	Esempio	Risultato
`[Class]` Collega a una classe	`Sposta lo [Sprite2D].`	Sposta lo Sprite2D.
`[annotation Class.name]` Collega a un'annotazione	`Vedi [annotation @GDScript.@rpc].`	Vedi @GDScript.@rpc.
`[constant Class.name]` Collega a una costante	`Vedi [constant Color.RED].`	Vedi Color.RED.
`[enum Class.name]` Collega a un'enumerazione	`Vedi [enum Mesh.ArrayType].`	Vedi Mesh.ArrayType.
`[member Class.name]` Collega a un membro (proprietà)	`Ottieni [member Node2D.scale].`	Ottieni Node2D.scale.
`[method Class.name]` Collega a un metodo	`Chiama [method Node3D.hide].`	Chiama Node3D.hide().
`[constructor Class.name]` Collega a un costruttore integrato	`Usa [constructor Color.Color].`	Usa Color.Color.
`[operator Class.name]` Collega a un operatore integrato	`Usa [operator Color.operator *].`	Usa Color.operator *.
`[signal Class.name]` Collega a un segnale	`Emetti [signal Node.renamed].`	Emetti Node.renamed.
`[theme_item Class.name]` Collega a un elemento del tema	`Vedi [theme_item Label.font].`	Vedi Label.font.
`[param name]` Nome di parametro (come codice)	`Accetta [param size] per le dimensioni.`	Accetta `size` per le dimensioni.
`[br]` Interruzione di riga	`Riga 1.[br]` `Riga 2.`	Riga 1. Riga 2.
`[lb]` `[rb]` `[` e `]` rispettivamente	`[lb]b[rb]testo[lb]/b[rb]`	[b]testo[/b]
`[b]` `[/b]` Grassetto	`[b]Non[/b] chiamare questo metodo.`	Non chiamare questo metodo.
`[i]` `[/i]` Corsivo	`Restituisce la posizione [i]globale[/i].`	Restituisce la posizione globale.
`[u]` `[/u]` Sottolinea	`Usa [u]sempre[/u] questo metodo.`	Always use this method.
`[s]` `[/s]` Barrato	`[s]Informazioni obsolete.[/s]`	~~Outdated information.~~
`[color]` `[/color]` Colore	`[color=red]Errore![/color]`	Error!
`[font]` `[/font]` Font	`[font=res://mono.ttf]LICENZA[/font]`	LICENSE
`[img]` `[/img]` Immagine	`[img width=32]res://icon.svg[/img]`
`[url]` `[/url]` Collegamento ipertestuale	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Sito web
`[center]` `[/center]` Centratura orizzontale	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Scorciatoia da tastiera/mouse	`Premi [kbd]Ctrl + C[/kbd].`	Premi `Ctrl + C`.
`[code]` `[/code]` Frammento di codice in riga	`Restituisce [code]true[/code].`	Restituisce `true`.
`[codeblock]` `[/codeblock]` Blocco di codice su più righe	Vedi sotto.	Vedi sotto.

Nota

Attualmente solo @GDScript contiene annotazioni.
[kbd] disattiva il BBCode finché il parser non incontra [/kbd].
[code] disattiva il BBCode finché il parser non incontra [/code].
[codeblock] disattiva il BBCode finché il parser non incontra [/codeblock].

Avvertimento

Utilizza [codeblock] per i blocchi di codice preformattati. Dentro [codeblock], usa sempre quattro spazi per l'indentazione (Il parser eliminerà le tabulazioni).

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

Normalmente, [codeblock] evidenzia la sintassi in GDScript. È possibile modificarla utilizzando l'attributo lang. Le opzioni attualmente supportate sono:

[codeblock lang=text] disabilita l'evidenziazione della sintassi;
[codeblock lang=gdscript] evidenzia la sintassi in GDScript;
[codeblock lang=csharp] evidenzia la sintassi in C# (solamente nella versione .NET).

Commenti di documentazione in GDScript

Documentare uno script

Tag

Documentare i membri di script

Tag

Esempio completo per uno script

Tag @deprecated e @experimental

BBCode e riferimento di classe

Tag `@deprecated` e `@experimental`