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.

Mejore el formato con etiquetas de estilo BBCode¶

Mejore el formato con etiquetas de estilo BBCode:

Etiqueta	Efecto	Uso	Resultado
[Class]	Enlazar a una clase	Mover el [Sprite].	Mover el Sprite.
[method methodname]	Enlazar a un método de esta clase	Llama [metodo hide].	Llama a hide.
[método Clase.nombremetodo]	Enlace al método de otra clase	Llama a [method Spatial.hide].	Llama a hide.
[miembro nombremiembro]	Enlazar a un miembro de esta clase	Obtiene [miembro escala].	Obtén scale.
[miembro Clase.nombremiembro]	Enlazar a otro miembro de la clase	Obtén [member Node2D.scale].	Obtén scale.
[signal nombresignal]	Enlazar con una señal de esta clase	Emita un [signal renamed].	Emita un renamed.
[señal Clase.nombreseñal]	Enlazar con la señal de otra clase	Emita un [signal Node.renamed].	Emita un renamed.
[b] [/b]	Negrita	Un texto en [b]negrita[/b].	Algo de texto en negrita.
[i] [/i]	Cursiva	Un texto en [i]cursiva[/i].	Algo de texto en cursiva.
[code] [/code]	Monospace	Un texto [code]monoespaciado[/code].	Algo de texto `monospace`.
[kbd] [/kbd]	Atajo del teclado/ratón	Alguna tecla [kbd]Ctrl + C[/kbd].	Alguna tecla `Ctrl + C`.
[codeblock] [/codeblock]	Bloque pre-formateado con múltiples líneas	Ver a continuación.	Ver a continuación.
[codeblocks] [/codeblocks]	[codeblock] para multiples lenguajes	Ver a continuación.	Ver a continuación.
[gdscript] [/gdscript]	Pestaña de bloque de código de GDScript en bloques de código	Ver a continuación.	Ver a continuación.
[csharp][/csharp]	Pestaña de bloque de código C# en bloques de código	Ver a continuación.	Ver a continuación.

Usa [codeblock] para bloques de código preformateados. Dentro de [codeblock], siempre utiliza cuatro espacios para la indentación. El analizador eliminará las tabulaciones. Por ejemplo:

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

Se mostrará como:

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

Si necesitas tener diferentes versiones de código en GDScript y C#, usa [codeblocks] en su lugar. Si usas [codeblocks], también debes tener al menos una de las etiquetas específicas del lenguaje, como [gdscript] y [csharp].

¡Siempre escribe ejemplos de código en GDScript primero! Puedes utilizar esta herramienta experimental de traducción de código para acelerar tu flujo de trabajo.

[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]

Lo anterior se mostrará como:

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

public override void _Ready()
{
    var sprite = GetNode("Sprite");
    GD.Print(sprite.GetPos());
}

Para denotar información importante, agrega un párrafo que comience con "[b]Nota:[/b]" al final de la descripción:

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

Para denotar información crucial que podría causar problemas de seguridad o pérdida de datos si no se sigue cuidadosamente, agrega un párrafo que comience con "[b]Advertencia:[/b]" al final de la descripción:

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

Para propiedades obsoletas, agrega un párrafo que comience con "[i]Obsoleto.[/i]". Observa el uso de cursiva en lugar de negrita:

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

Claro, en todos los párrafos descritos anteriormente, asegúrate de que la puntuación forme parte de las etiquetas BBCode para mantener la consistencia.

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