类参考编写规范

本页面将介绍如何编写类参考手册。你会学到去哪里为 Godot 内置节点类型的类、方法、属性编写新的描述。

参见

要学习如何使用 Git 版本控制系统向 Godot 项目提交你的修改，请参见 为类参考手册贡献。

每个类的参考文档都被包含在一个如下的 XML 文件中：

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

开头是简介和详细描述。在生成的文档中，顶部总是简介，详细描述会放在方法、变量、常量列表之后。可以看到方法、成员变量、常量、信号都在各自单独的 XML 节点中。

你会想要在 Godot 的源代码中学习它们都有什么用。然后补全或者完善这些标签中的文本：

• <brief_description>

• <description>

• <constant>

• <method>（在其 <description> 标签中；返回类型和参数不带单独的文档字符串）

• <member>

• <signal>（在其 <description> 标签中；参数不带单独的文档字符串）

• <constant>

用清晰简单的语言编写。始终遵循编写规范以使你的描述简短易读。在描述中不要留下空行：XML 文件中的每一行都将生成一个新段落，空行也是一样。

如何编辑类 XML

如果你想要更新某个类的类参考手册，编辑 doc/classes/ 中的对应文件即可。文件夹中包含了各个类的 XML 文件。在 XML 中，列出了类参考中的常量和方法。Godot 会自动生成并更新这些 XML。

备注

游戏引擎中某些模块的 XML 文件在 modules/<模块名称>/doc_classes/ 目录下。

用你喜欢的文本编辑器编辑它。如果你使用代码编辑器，请确保它不会改变缩进样式：XML 使用制表符，而 BBCode 风格的块内使用 4 个空格。下面有更多这方面的内容。

要检查你所做出的修改在生成后的文档中是否正确，请在 doc/ 文件夹中执行命令 make rst。这样就会将 XML 文件转换为在线文档的格式，存在错误时会有错误报告。

你也可以自行构建 Godot 然后在内置的类参考手册中打开被修改的页面。引擎的编译方法请查看 compilation guide。

我们推荐使用 Vim、Atom、Visual Studio Code、Notepad++ 等支持 XML 的代码编辑器，或者其他能够方便编辑此类文件的编辑器。你还可以使用它们的搜索功能快速查找类和属性。

使用 BBCode 风格标签来改进格式

Godot的类参考支持类似BBCode的标签. 它们为文本添加了漂亮的格式. 下面是可用标签的列表:

对预格式化的代码块使用 [codeblock]。在 [codeblock] 中，请始终使用四个空格进行缩进。解析器将删除制表符。例如：

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

将显示为：

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

如果你有针对 GDScript 和 C# 的不同版本的代码，请换用 [codeblocks]。使用 [codeblocks]，你还需要至少一个语言标签，即 [gdscript] 和 [csharp]。

请先写 GDScript 代码示例！你可以使用这个实验性的代码翻译工具来加速工作流程。

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

上述内容将显示为：

GDScriptC#

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

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

要表示重要信息，请在描述末尾添加一段以“[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标签的一部分, 以保持一致性.

我不知道这个方法干什么用！

没问题. 将其留下, 并在你请求提取更改时列出跳过的方法. 别的编写者会处理它.

你仍然可以在 GitHub 上查看 Godot 的源代码。如果你有疑问，请随时在问答网站和 Godot 贡献者聊天上提问。