Up to date

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

GDSCript Commentaires de documentation

Dans GDScript, les commentaires peuvent être utilisés pour documenter votre code et ajouter des descriptions aux parties d'un script. Il existe deux différences entre un commentaire normal et un commentaire de documentation. Tout d'abord, un commentaire de documentation doit commencer par un double symbole dièse ##. Ensuite, il doit précéder immédiatement une partie de script ou, pour les descriptions de script, être placé en haut du script. Si une variable exportée est documentée, sa description est utilisée comme info-bulle dans l'éditeur. Cette documentation peut être générée sous forme de fichiers XML par l'éditeur.

Documenter un script

Les commentaires documentant un script doivent précéder toute documentation relative aux autres parties du script. Le format suggéré pour la documentation d'un script peut être divisé en trois parties.

Une brève description du script.
Une description détaillée.
Des tutoriels et marques dépréciées/expérimentales.

Pour les séparer les uns des autres, les commentaires de la documentation utilisent des étiquettes spéciales. L'étiquette doit être au début d'une ligne (en ignorant l'espace blanc qui la précède) et doit avoir le format @, suivi du mot-clé.

Étiquettes

Courte description	Aucune étiquette. Se trouve au tout début de la section de documentation.
Description	Pas d'étiquette. Utilisez une ligne vide pour la séparer de la courte description.
Tutoriel	`@tutorial: https://example.com` `@tutorial(Le titre ici): https://example.com`
Obsolète	`@deprecated` `@deprecated: Utilisez [AutreClasse] à la place.`
Expérimental	`@experimental` `@experimental: Cette classe est instable.`

Par exemple :

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

Avertissement

S'il y a un espace entre le nom de la balise et les deux points, par exemple @tutorial :, il ne sera pas traité comme une balise valide et sera ignoré.

Note

Lorsque la description s'étend sur plusieurs lignes, les espaces blancs précédant et suivant les lignes seront supprimés et joints par un seul espace. Pour préserver le saut de ligne, utilisez [br]. Voir également BBCode and class reference ci-dessous.

Documentation des parties du script

Parties pouvant faire l'objet d'une entrée dans la documentation :

Signaux
Énumération
Valeur d’énumération
Constante
Variable
Fonction
Classe interne

La documentation d'un membre du script doit précéder immédiatement le membre ou ses annotations s'il en contient. La description peut comporter plusieurs lignes, mais chaque ligne doit commencer par le symbole dièse double ## pour être considérée comme faisant partie de la documentation.

Étiquettes

Description	Aucune étiquette.
Obsolète	`@deprecated` `@deprecated: Utiliser [autre membre] à la place.`
Expérimental	`@experimental` `@experimental: Cette méthode n'est pas terminée.`

Par exemple :

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

Autrement, vous pouvez utiliser des commentaires sur la même ligne:

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 documentation du script sera mise à jour dans la fenêtre d'aide de l'éditeur à chaque mise à jour du script. Si le nom d'une propriété ou d'une fonction commence par un trait de soulignement, il sera traité comme privé. Il n'apparaîtra pas dans la documentation et sera ignoré dans la fenêtre d'aide.

Exemple complet pour un 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

Etiquettes `@deprecated` et `@experimental`

Vous pouvez marquer une classe ou l'un de ses membres comme obsolète ou expérimental. Cela ajoutera l'indicateur correspondant dans la visionneuse de documentation intégrée. Vous pouvez éventuellement fournir un court message expliquant pourquoi l'API n'est pas recommandée. Cela peut être particulièrement utile pour les créateurs de plugins et de bibliothèques.

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

Deprecated indique une API non recommandée qui est susceptible d'être supprimée ou de subir une modification incompatible dans une future version majeure. En général, l'API est conservée pour des raisons de compatibilité ascendante.
Experimental indique une nouvelle API instable qui peut être modifiée ou supprimée dans la branche principale actuelle. L'utilisation de cette API n'est pas recommandée dans le code de production.

Note

Bien que techniquement vous puissiez utiliser les balises @deprecated et @experimental sur la même classe/membre, cela n'est pas recommandé car cela va à l'encontre des conventions courantes.

BBCode et référence de classe

La référence de classe de Godot prend en charge les balises de type BBCode. Ils ajoutent une belle mise en forme au texte qui pourrait également être utilisée dans la documentation. Voir aussi bbcode pour les références de classe. Notez que cela est légèrement différent du RichTextLabel BBCode.

Chaque fois que vous créez un lien vers un membre d'une autre classe, vous devez spécifier le nom de la classe. Pour les liens vers la même classe, le nom de la classe est facultatif et peut être omis.

Voici la liste des étiquettes disponibles :

Étiquettes et Description	Exemple	Résultat
`[Class]` Lien vers une classe	`Déplacer le [Sprite2D].`	Déplacez le Sprite2D.
`[annotation Class.name]` Lien vers l'annotation	`Voir [annotation @GDScript.@rpc].`	Voir @GDScript.@rpc.
`[constant Class.name]` Lien vers une constante	`Voir [constant Color.RED].`	Voir Color.RED.
`[enum Class.name]` Lien vers l'énumération	`Voir [enum Mesh.ArrayType].`	Voir Mesh.ArrayType.
`[member Class.name]` Lien vers le membre (propriété)	`Obtenir [member Node2D.scale].`	Obtenir Node2D.scale.
`[method Class.name]` Lien vers une méthode	`Appelle [method Node3D.hide].`	Appelle Node3D.hide().
`[constructor Class.name]` Lien vers le constructeur intégré	`Utilise [constructor Color.Color].`	Utilise  Color.Color.
`[operator Class.name]` Lien vers un opérateur intégré	`Utilise [operator Color.operator *].`	Utilise  Color.operator *.
`[signal Class.name]` Lien vers un signal	`Émet [signal Node.renamed].`	Émet Node.renamed.
`[theme_item Class.name]` Lien vers un objet du thème	`Voir [theme_item Label.font].`	Voir Label.font.
`[param name]` Nom de paramètre (comme code)	`Prends [param size] pour la taille.`	Prends `size` pour la taille.
`[br]` Saut de ligne	`Ligne 1.[br]` `Ligne 2.`	Ligne 1. Ligne 2.
`[lb]` `[rb]` `[` et `]` respectivement	`[lb]b[rb]texte[lb]/b[rb]`	[b]texte[/b]
`[b]` `[/b]` Gras	`[b]Ne pas[/b] appeler cette méthode.`	Ne pas appeler cette méthode.
`[i]` `[/i]` Italique	`Retourne la position [i]globale[/i].`	Retourne la position globale.
`[u]` `[/u]` Souligné	`[u]Toujours[/u] utiliser cette méthode.`	Always use this method.
`[s]` `[/s]` Barré	`[s]Information plus à jour.[/s]`	~~Outdated information.~~
`[color]` `[/color]` Couleur	`[color=red]Erreur![/color]`	Error!
`[font]` `[/font]` Police	`[font=res://mono.ttf]LICENSE[/font]`	LICENSE
`[img]` `[/img]` Image	`[img width=32]res://icon.svg[/img]`
`[url]` `[/url]` Lien web	`[url]https://example.com[/url]` `[url=https://example.com]site Web[/url]`	https://example.com `site Web<https://example.com>`_
`[center]` `[/center]` Centrage horizontal	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Raccourci clavier/souris	`Appuyez sur [kbd]Ctrl + C[/kbd].`	Appuyez sur `Ctrl + C`.
`[code]` `[/code]` Fragment de code inline	`Renvoie [code]true[/code].`	Renvoie `true`.
`[codeblock]` `[/codeblock]` Bloc de code multiligne	Voir ci-dessous.	Voir ci-dessous.

Note

Actuellement, seul @GDScript contient des annotations.
[kbd] désactive le BBCode jusqu'à ce que l'analyseur rencontre [/kbd].
[code] désactive le BBCode jusqu'à ce que l'analyseur rencontre [/code].
[codeblock] désactive le BBCode jusqu'à ce que l'analyseur rencontre [/codeblock].

Avertissement

Utilisez [codeblock] pour les blocs de code préformatés. À l'intérieur de [codeblock], utilisez toujours quatre espaces pour l'indentation (l'analyseur supprimera les tabulations).

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

Par défaut, [codeblock] met en surbrillance la syntaxe GDScript. Vous pouvez la modifier à l'aide de l'attribut lang. Les options actuellement prises en charge sont :

[codeblock lang=text] désactive la coloration syntaxique ;
[codeblock lang=gdscript] met en évidence la syntaxe GDScript ;
[codeblock lang=csharp] met en évidence la syntaxe C# (uniquement dans la version .NET).

GDSCript Commentaires de documentation

Documenter un script

Étiquettes

Documentation des parties du script

Étiquettes

Exemple complet pour un script

Etiquettes @deprecated et @experimental

BBCode et référence de classe

Etiquettes `@deprecated` et `@experimental`