Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
GDScript 文档注释¶
GDScript 文档注释也可以用来为你的代码中的成员提供文档说明。普通注释和文档注释有两点区别,其一:文档注释均以 ##
开头;其二:文档注释必须写在成员声明之前,亦或写于脚本顶部来为脚本提供基本说明。若使用文档注释注释了导出变量,则可在编辑器中通过悬停窗来查看该导出变量的文档注释。文档注释也可以由编辑器生成为 XML 文档。
为脚本编写文档¶
使用文档注释编写脚本文档时,必须写于成员声明之前。这里推荐大家将脚本文档分为以下三块编写。
脚本类概述。
脚本类详细描述。
教程与特殊标记——废弃标记/实验性标记。
为了将这些部分区分开来,文档注释采用了一些特殊标记。特殊标记须写于文本行开头(忽略其之前的空格),且需要以 @
符号开头,后接标记名。
为脚本类成员编写文档¶
脚本类成员也可以使用文档注释来生成对应文档说明:
内部类
常量
函数
信号
变量
枚举
枚举值
对于脚本类成员,为其编写文档注释时应写在该成员及修饰该成员的注解(若存在注解)之前。在编写脚本类成员的文档注释时也可以进行多行编写,但每行均须以双井号 ##
开头,以保证这几行的内容均为该成员的文档注释。
标记¶
描述 |
无标记。 |
已弃用 |
|
实验性 |
|
例如:
## The description of the variable.
## @deprecated
var my_var
或者你也可以手动调用 sphinx-build 程序来构建文档::
enum MyEnum { ## My enum.
VALUE_A = 0, ## Value A.
VALUE_B = 1, ## Value B.
}
const MY_CONST = 1 ## My constant.
var my_var ## My variable.
signal my_signal ## My signal.
func my_func(): ## My func.
pass
class MyClass: ## My class.
pass
只要脚本内容发生变化,该脚本的类文档便会自动更新。若存在以下划线开头的变量或函数,则该变量/函数就会视为私有变量/私有函数,不会显示在该脚本的脚本类文档当中。
完整脚本示例¶
extends Node2D
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
##
## @tutorial: https://the/tutorial1/url.com
## @tutorial(Tutorial2): https://the/tutorial2/url.com
## @experimental
## The description of a constant.
const GRAVITY = 9.8
## The description of a signal.
signal my_signal
## This is a description of the below enum.
enum Direction {
## Direction up.
UP = 0,
## Direction down.
DOWN = 1,
## Direction left.
LEFT = 2,
## Direction right.
RIGHT = 3,
}
## The description of the variable v1.
var v1
## This is a multiline description of the variable v2.[br]
## The type information below will be extracted for the documentation.
var v2: int
## If the member has any annotation, the annotation should
## immediately precede it.
@export
var v3 := some_func()
## As the following function is documented, even though its name starts with
## an underscore, it will appear in the help window.
func _fn(p1: int, p2: String) -> int:
return 0
# The below function isn't documented and its name starts with an underscore
# so it will treated as private and will not be shown in the help window.
func _internal() -> void:
pass
## Documenting an inner class.
##
## The same rules apply here. The documentation must
## immediately precede the class definition.
##
## @tutorial: https://the/tutorial/url.com
## @experimental
class Inner:
## Inner class variable v4.
var v4
## Inner class function fn.
func fn(): pass
BBCode 与类参考¶
编辑器帮助窗口的文档界面支持 bbcode,这样一来,就能够使用 BBCode 对你的文档进行对齐与排版操作。文本颜色、图片、字体、表格、URL 链接和动画等元素可通过 bbcode 来加入到文档当中。
Godot 的类参考支持类似 BBCode 的标签。这些标签用在文档中时可以让文本格式更加美观。另见类参考 BBCode。
每从其他类里链接一个成员,你都要在成员名前面加上该类的类名。而链接类内成员时,类名可省略。
可用的标记如下:
描述 |
示例 |
结果 |
---|---|---|
[Class] 链接类
|
|
移动 Sprite2D。 |
[annotation Class.name] 链接到注解
|
|
|
[constant Class.name] 链接到常量
|
|
|
[enum Class.name] 链接到枚举
|
|
|
[method Class.name] 链接到方法
|
|
调用 Node3D.hide()。 |
[member Class.name] 链接到成员
|
|
获取 Node2D.scale. |
[signal Class.name] 链接到信号
|
|
发送 Node.renamed。 |
[theme_item Class.name] 链接到主题项
|
|
见 Label.font。 |
[param name] 格式化参数名称(作为代码)
|
|
用 |
[br] 换行
|
行 1。[br] 行 2。 |
行 1。
行 2。
|
[b] [/b] 粗体
|
|
一些粗体文本。 |
[i] [/i] 斜体
|
|
一些斜体文本。 |
[kbd] [/kbd] 键盘和鼠标快捷键
|
|
一些 Ctrl + C 按键。 |
[code] [/code] 等宽字体
|
|
一些 |
[codeblock] [/codeblock] 多行预格式化块
|
见下文. |
见下文. |
备注
目前只有 @GDScript 有注解。
[code]
与[/code]
之间的 BBCode 代码均无效。[codeblock]
与[/codeblock]
之间的 BBCode 代码均无效。
警告
使用 [codeblock]
来制作预格式化代码块。在 [codeblock]
区域中,请始终使用四个空格进行缩进,解析器会删除制表符。
## Do something for this plugin. Before using the method
## you first have to [method initialize] [MyPlugin].[br]
## [color=yellow]Warning:[/color] Always [method clean] after use.[br]
## Usage:
## [codeblock]
## func _ready():
## the_plugin.initialize()
## the_plugin.do_something()
## the_plugin.clean()
## [/codeblock]
func do_something():
pass