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