Directrices para escribir la referencia de clases¶
Esta página explica cómo escribir la referencia de clases. Aprenderás dónde escribir nuevas descripciones para las clases, métodos y propiedades de los tipos de nodos incorporados en Godot.
Ver también
Para aprender a enviar tus cambios al proyecto Godot utilizando el sistema de control de versiones Git, consulta Contribuyendo a la referencia de la clase.
La referencia para cada clase se encuentra en un archivo XML como el que se muestra a continuación:
<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>
Comienza con descripciones breves y largas. En la documentación generada, la descripción breve siempre está en la parte superior de la página, mientras que la descripción larga se encuentra debajo de la lista de métodos, variables y constantes. Puedes encontrar métodos, variables miembro, constantes y señales en nodos XML separados.
Para cada uno de ellos, deseas aprender cómo funcionan en el código fuente de Godot. Luego, completa o mejora su documentación rellenando los textos en estas etiquetas:
<brief_description>
<description>
<constant>
<method> (en su etiqueta <description>; los tipos de retorno y los argumentos no requieren descripciones separadas)
<member>
<signal> (en su etiqueta <description>; los argumentos no requieren descripciones separadas)
<constant>
Escribe en un lenguaje claro y sencillo. Siempre sigue las pautas de escritura para mantener tus descripciones cortas y fáciles de leer. No dejes líneas vacías en las descripciones: cada línea en el archivo XML resultará en un nuevo párrafo, incluso si está vacía.
Cómo editar una clase XML¶
Edita el archivo de la clase que elijas en doc/classes/
para actualizar la referencia de la clase. La carpeta contiene un archivo XML para cada clase. El XML lista las constantes y métodos que encontrarás en la referencia de la clase. Godot genera y actualiza automáticamente el XML.
Nota
Para algunos módulos en el código fuente del motor, encontrarás los archivos XML en el directorio modules/<nombre_del_modulo>/doc_classes/
.
Edítalo usando tu editor de texto favorito. Si utilizas un editor de código, asegúrate de que no cambie el estilo de sangría: debes usar tabulaciones para el XML y cuatro espacios dentro de bloques de estilo BBCode. Más detalles a continuación.
Para comprobar que las modificaciones que has realizado son correctas en la documentación generada, navega hasta la carpeta doc/
y ejecuta el comando make rst
. Esto convertirá los archivos XML al formato de la documentación en línea y mostrará errores si algo está mal.
Como alternativa, puedes compilar Godot y abrir la página modificada en la referencia de código integrada. Para aprender cómo compilar el motor, lee la guía de compilación.
Recomendamos usar un editor de código que admita archivos XML como Vim, Atom, Visual Studio Code, Notepad++ u otro para editar cómodamente el archivo. También puedes utilizar su función de búsqueda para encontrar clases y propiedades rápidamente.
¡No sé que hace este método!¶
No hay problema. Déjalo atrás, y enumera los métodos que omitiste cuando solicitaste un pull de tus cambios. Otro redactor se encargará de ello.
Aún puedes ver la implementación de los métodos en el código fuente de Godot en GitHub. Si tienes dudas, no dudes en preguntar en el sitio de preguntas y respuestas (Q&A website) y en el Godot Contributors Chat.