类参考编写规范

本页面将介绍如何编写类参考手册。你会学到去哪里为 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的标签. 它们为文本添加了漂亮的格式. 下面是可用标签的列表:

标签

效果

用法

结果

[Class]

链接到一个类

移动 [Sprite]。

移动 Sprite

[method methodname]

链接到此类中的方法

调用 [method hide]。

调用 hide

[method Class.methodname]

链接到另一个类的方法

调用 [method Spatial.hide]。

调用 hide

[member membername]

链接到这个类的成员

获得[member scale].

获取 scale

[member Class.membername]

链接到另一个类的成员

获得 [member Node2D.scale].

获取 scale

[signal signalname]

链接到此类中的信号

发射 [signal renamed].

触发 renamed

[signal Class.signalname]

链接到另一个类的信号

发射 [signal Node.renamed].

触发 renamed

[b] [/b]

粗体

一些[b]粗体[/b]文字.

一些 粗体 文字.

[i] [/i]

斜体

一些[i]斜体[/i]文字.

一些 斜体 文字.

[code] [/code]

等宽字体

一些 [code]等宽字体[/code] 文本。

一些 等宽字体 文本.

[kbd] [/kbd]

键盘和鼠标快捷键

一些 [kbd]Ctrl + C[/kbd] 键。

一些 Ctrl + C 键.

[codeblock] [/codeblock]

多行预格式化块

见下文.

见下文.

[codeblocks] [/codeblocks]

多语言的 [codeblock] 代码块

见下文.

见下文.

[gdscript] [/gdscript]

代码块中的 GDScript 代码块选项卡

见下文.

见下文.

[csharp] [/csharp]

代码块中的 C# 代码块选项卡

见下文.

见下文.

对预格式化的代码块使用 [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]

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]

上述内容将显示为:

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标签的一部分, 以保持一致性.

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

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

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