Class reference writing guidelines

This page explains how to write the class reference. You will learn where to write new descriptions for the classes, methods, and properties for Godot's built-in node types.

也參考

To learn to submit your changes to the Godot project using the Git version control system, see 參與貢獻類別參照文件.

The reference for each class is contained in an XML file like the one below:

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

It starts with brief and long descriptions. In the generated docs, the brief description is always at the top of the page, while the long description lies below the list of methods, variables, and constants. You can find methods, member variables, constants, and signals in separate XML nodes.

For each, you want to learn how they work in Godot's source code. Then, fill their documentation by completing or improving the text in these tags:

• <brief_description>

• <description>

• <constant>

• <method> (in its <description> tag; return types and arguments don't take separate documentation strings)

• <member>

• <signal> (in its <description> tag; arguments don't take separate documentation strings)

• <constant>

Write in a clear and simple language. Always follow the writing guidelines to keep your descriptions short and easy to read. Do not leave empty lines in the descriptions: each line in the XML file will result in a new paragraph, even if it is empty.

如果編輯類別 XML

Edit the file for your chosen class in doc/classes/ to update the class reference. The folder contains an XML file for each class. The XML lists the constants and methods you will find in the class reference. Godot generates and updates the XML automatically.

備註

For some modules in the engine's source code, you'll find the XML files in the modules/<module_name>/doc_classes/ directory instead.

Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: you should use tabs for the XML and four spaces inside BBCode-style blocks. More on that below.

To check that the modifications you've made are correct in the generated documentation, navigate to the doc/ folder and run the command make rst. This will convert the XML files to the online documentation's format and output errors if anything's wrong.

Alternatively, you can build Godot and open the modified page in the built-in code reference. To learn how to compile the engine, read the compilation guide.

We recommend using a code editor that supports XML files like Vim, Atom, Visual Studio Code, Notepad++, or another to comfortably edit the file. You can also use their search feature to find classes and properties quickly.

使用 BBCode 風格的標籤來增強格式

Godot 的類別參照文件支援類似 BBCode 的標籤。這些標籤可以為文字加上格式。下面列出了所有可用的標籤：

Tag	效果	使用量	結果
[Class]	類別連結	Move the [Sprite].	Move the Sprite.
[method 方法名稱]	該類別中方法的連結	呼叫 [method hide]。	Call hide.
[method 類別.方法名稱]	另一個類別的方法連結	Call [method Spatial.hide].	Call hide.
[member 成員名稱]	該類別中成員的連結	取得 [member scale]。	Get scale.
[member 類別.成員名稱]	另一個方法的成員連結	取得 [member Node2D.scale]。	Get scale.
[signal 訊號名稱]	該類別訊號的連結	發送 [signal renamed]。	Emit renamed.
[signal 類別.訊號名稱]	另一個類別的訊號連結	發送 [signal Node.renamed]。	Emit renamed.
[b] [/b]	粗體	普通的 [b]粗體[/b] 文字。	普通的 粗體 文字。
[i] [/i]	斜體	普通的 [i]斜體[/i] 文字。	普通的 斜體 文字。
[code] [/code]	等寬字體	普通的 [code]等寬字體 (Monospace)[/code] 文字。	普通的 等寬字體 (Monospace) 文字。
[kbd] [/kbd]	鍵盤或滑鼠快捷鍵	普通的 [kbd]Ctrl + C[/kbd] 按鍵。	普通的 Ctrl + C 按鍵。
[codeblock] [/codeblock]	多行預格式化區塊	參見下方。	參見下方。
[codeblocks] [/codeblocks]	[codeblock] for multiple languages	參見下方。	參見下方。
[gdscript] [/gdscript]	GDScript codeblock tab in codeblocks	參見下方。	參見下方。
[csharp] [/csharp]	C# codeblock tab in codeblocks	參見下方。	參見下方。

Use [codeblock] for pre-formatted code blocks. Inside [codeblock], always use four spaces for indentation. The parser will delete tabs. For example:

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

會顯示為：

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

If you need to have different code version in GDScript and C#, use [codeblocks] instead. If you use [codeblocks], you also need to have at least one of the language-specific tags, [gdscript] and [csharp].

Always write GDScript code examples first! You can use this experimental code translation tool to speed up your workflow.

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

The above will display as:

GDScriptC#

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

若要標記出重要的資訊，可在說明最後新增以「[b]Note:[/b]」開頭的段落：

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

若要標記出未多加留意可能導致安全性問題或遺失資料的警示資訊，請在說明最後加上以「[b]Warning:[/b]」開頭的段落：

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

而已停止維護的屬性，請加上以「[i]Deprecated.[/i]」開頭的段落。請注意，這裡使用的是斜體而非粗體：

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

請注意，上面描述的所有段落中，標點符號都是 BBCode 標籤中的一部分，請保持一致性。

我不知道這個方法做了什麼！

沒關係，先跳過即可。並請在為更改開啟 PR 時列出所有跳過的方法。其他編寫者會處理這些方法。

You can still look at the methods' implementation in Godot's source code on GitHub. If you have doubts, feel free to ask on the Q&A website and Godot Contributors Chat.