Directives pour la rédaction des références de classe

Cette page explique comment écrire la référence de la classe. Vous apprendrez où écrire de nouvelles descriptions pour les classes, les méthodes et les propriétés des types de nœuds intégrés de Godot.

Voir aussi

Pour apprendre à soumettre vos modifications au projet Godot en utilisant le système de contrôle de version Git, consultez Contribuer à la référence des classes.

La référence de chaque classe est contenue dans un fichier XML comme celui ci-dessous :

<class name="Node2D" inherits="CanvasItem" version="4.0">
    <brief_description>
        A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
    </brief_description>
    <description>
        A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
    </description>
    <tutorials>
        <link title="Custom drawing in 2D">https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link>
        <link title="All 2D Demos">https://github.com/godotengine/godot-demo-projects/tree/master/2d</link>
    </tutorials>
    <methods>
        <method name="apply_scale">
            <return type="void">
            </return>
            <argument index="0" name="ratio" type="Vector2">
            </argument>
            <description>
                Multiplies the current scale by the [code]ratio[/code] vector.
            </description>
        </method>
        [...]
        <method name="translate">
            <return type="void">
            </return>
            <argument index="0" name="offset" type="Vector2">
            </argument>
            <description>
                Translates the node by the given [code]offset[/code] in local coordinates.
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
            Global position.
        </member>
        [...]
        <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
            Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others.
        </member>
    </members>
    <constants>
    </constants>
</class>

Cela commence par des descriptions brèves et longues. Dans la documentation générée, la description brève se trouve toujours en haut de la page, tandis que la description longue se trouve sous la liste des méthodes, des variables et des constantes. Vous pouvez trouver les méthodes, les variables membres, les constantes et les signaux dans des nœuds XML distincts.

Pour chacun, vous voulez apprendre comment ils fonctionnent dans le code source de Godot. Ensuite, remplissez leur documentation en complétant ou en améliorant le texte de ces balises :

  • <brief_description>

  • <description>

  • <constant>

  • <method> (dans sa balise <description> ; les types de retour et les arguments ne prennent pas de chaînes de documentation séparées)

  • <member>

  • <signal> (dans sa balise <description> ; les arguments ne prennent pas de chaînes de documentation séparées)

  • <constant>

Écrivez dans un langage clair et simple. Suivez toujours les directives d’écriture pour garder vos descriptions courtes et faciles à lire. Ne laissez pas de lignes vides dans les descriptions : chaque ligne du fichier XML entraînera un nouveau paragraphe, même s’il est vide.

Comment modifier la classe XML

Modifiez le fichier de la classe choisie dans doc/classes/ pour mettre à jour la référence de la classe. Le dossier contient un fichier XML pour chaque classe. Le XML liste les constantes et les méthodes que vous trouverez dans la référence de la classe. Godot génère et met à jour le XML automatiquement.

Note

Pour certains modules du code source du moteur, vous trouverez les fichiers XML dans le répertoire modules/<module_name>/doc_classes/ à la place.

Modifiez-le en utilisant votre éditeur de texte préféré. Si vous utilisez un éditeur de code, assurez-vous qu'il ne modifie pas le style d'indentation : vous devez utiliser des tabulations pour le XML et quatre espaces à l'intérieur des blocs de style BBCode. Plus d'informations à ce sujet ci-dessous.

Pour vérifier que les modifications que vous avez faites sont correctes dans la documentation générée, naviguez dans le dossier doc/ et exécutez la commande make rst. Cela convertira les fichiers XML au format de la documentation en ligne et affichera des erreurs si quelque chose ne va pas.

Alternativement, vous pouvez construire Godot et ouvrir la page modifiée dans la référence de code intégrée. Pour savoir comment compiler le moteur, lisez le guide de compilation.

Nous vous recommandons d'utiliser un éditeur de code prenant en charge les fichiers XML comme Vim, Atom, Visual Studio Code, Notepad++ ou autre pour éditer confortablement le fichier. Vous pouvez également utiliser leur fonction de recherche pour trouver rapidement les classes et les propriétés.

Améliorez le formatage avec les balises de style BBcode

La référence de classe de Godot supporte les balises de type BBcode. Ils ajoutent un joli formatage au texte. Voici la liste des balises disponibles :

Balise

Effet

Utilisation

Résultat

[Class]

Lier une classe

Déplacez le [Sprite].

Déplacez le Sprite.

[method methodname]

Lien vers une méthode dans cette classe

Appelez [method hide].

Appelez hide.

[method Class.methodname]

Lien vers la méthode d'une autre classe

Call [method Spatial.hide].

Appelez hide.

[member membername]

Lien vers un membre dans cette classe

Obtenir [member scale].

Obtenir scale.

[member Class.membername]

Lien vers un membre d'une autre classe

Obtenir [member Node2D.scale].

Obtenir scale.

[signal signalname]

Lien vers un signal dans cette classe

Émettre [signal renamed].

Émettre renamed.

[signal Class.signalname]

Lien vers le signal d'une autre classe

Émettre [signal Node.renamed].

Émettre renamed.

[b] [/b]

Gras

Du texte en [b]gras[/b].

Du texte en gras.

[i] [/i]

Italique

Du texte en [i]italique[/i].

Du texte italique.

[code] [/code]

Monospace

Du texte [code]monospace[/code].

Du texte monospace.

[kbd] [/kbd]

Raccourci clavier/souris

Des touches [kbd]Ctrl + C[/kbd].

Des touches Ctrl + C.

[codeblock] [/codeblock]

Bloc multiligne préformaté

Voir ci-dessous.

Voir ci-dessous.

[codeblocks] [/codeblocks]

[codeblock] pour de multiples langages

Voir ci-dessous.

Voir ci-dessous.

[gdscript] [/gdscript]

Onglet GDScript codeblock dans codeblocks

Voir ci-dessous.

Voir ci-dessous.

[csharp] [/csharp]

C# codeblock tab dans codeblocks

Voir ci-dessous.

Voir ci-dessous.

Utiliser [codeblock] pour des blocs de code préformatés. À l'intérieur de [codeblock], utiliser toujours quatre espaces pour l'indentation. L'analyseur(parser) supprimera les tabulations. Par exemple :

[codeblock]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/codeblock]

S'affichera comme cela :

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

Si vous avez besoin d'avoir une version de code différente en GDScript et en C#, utilisez plutôt [codeblocks]. Si vous utilisez [codeblocks], vous devez aussi avoir au moins une des balises spécifiques au langage, [gdscript] et [csharp].

Commencez toujours par écrire des exemples de code GDScript ! Vous pouvez utiliser cet outil expérimental de traduction de code pour accélérer votre flux de travail.

[codeblocks]
[gdscript]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/gdscript]
[csharp]
public override void _Ready()
{
    var sprite = GetNode("Sprite");
    GD.Print(sprite.GetPos());
}
[/csharp]
[/codeblocks]

Ce qui précède s'affichera comme suit :

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

Pour signaler des informations importantes, ajoutez un paragraphe commençant par "[b]Note :[/b]" à la fin de la description :

[b]Note:[/b] Only available when using the Vulkan renderer.

Pour indiquer les informations cruciales qui pourraient entraîner des problèmes de sécurité ou la perte de données si elles ne sont pas suivies attentivement, ajoutez un paragraphe commençant par "[b]Warning:[/b]" à la fin de la description :

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

Pour les propriétés obsolètes, ajoutez un paragraphe commençant par "[i]Deprecated.[/i]". Notez l'utilisation de l'italique au lieu du gras :

[i]Deprecated.[/i] This property has been replaced by [member other_property].

Dans tous les paragraphes décrits ci-dessus, assurez-vous que la ponctuation fait partie des balises BBCode pour des raisons de cohérence.

Je ne sais pas ce que cette méthode fait !

Aucun problème. Laissez-le derrière et lister les méthodes que vous avez passé quand vous faites un pull request de vos changements. Un autre contributeur s'en occupera.

Vous pouvez toujours regarder l'implémentation des méthodes dans le code source de Godot sur GitHub. Ainsi, si vous avez des doutes, n'hésitez pas à poser des questions sur le site web Q&R et sur le Chat des Contributors de Godot.