GDScript 文档注释

GDScript 文档注释

GDScript 文档注释也可以用来为你的代码中的成员提供文档说明。普通注释和文档注释有两点区别，其一：文档注释均以 ## 开头；其二：文档注释必须写在成员声明之前，亦或写于脚本顶部来为脚本提供基本说明。若使用文档注释注释了导出变量，则可在编辑器中通过悬停窗来查看该导出变量的文档注释。文档注释也可以由编辑器生成为 XML 文档。

为脚本编写文档

使用文档注释编写脚本文档时，必须写于成员声明之前。这里推荐大家将脚本文档分为以下三块编写。

脚本类概述。
脚本类详细描述。
教程与特殊标记——废弃标记/实验性标记。

为了将这些部分区分开来，文档注释采用了一些特殊标记。特殊标记须写于文本行开头（忽略其之前的空格），且需要以 @ 符号开头，后接标记名。

标记

Brief description	无标记，仅位于文档开头部分。
描述	无标记，用一行空的文档注释行来与文档概述隔开。
文字教程	`@tutorial:` `@tutorial(标题写在此处):`
已弃用	`@deprecated`
实验性	`@experimental`

例如：

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

警告

若标记名和冒号中间存在空格，如 @tutorial :，则不会将该标记视为有效标记，该无效标记将会被引擎忽略。

备注

文档注释若描述超过一行，则改行文档注释文本的末尾空格与下一行文档注释文本的开头空格将会在显示时自动缩合成一个空格，且不会换行。若必须换行，请使用换行符 [br] 。也可见下方的 BBCode and class reference 。

为脚本类成员编写文档

脚本类成员也可以使用文档注释来生成对应文档说明：

内部类
常量
函数
信号
变量
枚举
枚举值

对于脚本类成员，为其编写文档注释时应写在该成员及修饰该成员的注解（若存在注解）之前。在编写脚本类成员的文档注释时也可以进行多行编写，但每行均须以双井号 ## 开头，以保证这几行的内容均为该成员的文档注释。

标记

描述	无标记。
已弃用	`@deprecated`
实验性	`@experimental`

例如：

## 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 a constant.
const GRAVITY = 9.8
## 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

文档注释标记 `@deprecated` 和 `@experimental`

你可以将一个类或其成员标记为已废弃成员或者实验性成员，标记后，引擎就会在文档查看器里自动添加上对应提示符号，对插件和代码库的作者而言无疑是一大福音。

已废弃 标记不推荐的 API，该 API 可能会在未来的主要版本中移除或进行不兼容的更改。保留 API 通常是为了向后兼容。
实验性 标记了一个新的不稳定 API，该 API 可能会在当前主要分支中更改或移除。不建议在生产代码中使用该 API。

备注

当然，技术上来说，你可以给同一个类/成员同时使用 @deprecated and @experimental 这两个标记，不过并不推荐这样做，会比较反直觉。

BBCode 与类参考

编辑器帮助窗口的文档界面支持 bbcode，这样一来，就能够使用 BBCode 对你的文档进行对齐与排版操作。文本颜色、图片、字体、表格、URL 链接和动画等元素可通过 bbcode 来加入到文档当中。

Godot 的类参考支持类似 BBCode 的标签。这些标签可以为文本添加美观的格式，也可以用在文档中。另见类参考 BBCode。

每从其他类里链接一个成员，你都要在成员名前面加上该类的类名。而链接类内成员时，类名可省略。

可用的标记如下：

描述	示例	结果
`[Class]` 链接类	`移动 [Sprite]。`	移动 Sprite2D。
`[annotation Class.name]` 链接到注解	`见 [annotation @GDScript.@export].`	见 @GDScript.@export。
`[constant Class.name]` 链接到常量	`见 [constant @GlobalScope.KEY_F1]。`	见 @GlobalScope.KEY_F1。
`[enum Class.name]` 链接到枚举	`见 [enum Mesh.ArrayType]。`	见 Mesh.ArrayType。
`[method Class.name]` 链接到方法	`调用 [method Node3D.hide].`	调用 Node3D.hide()。
`[member Class.name]` 链接到成员	`获取 [member Node2D.scale]。`	获取 Node2D.scale.
`[signal Class.name]` 链接到信号	`发送 [signal Node.renamed]。`	发送 Node.renamed。
`[theme_item Class.name]` 链接到主题项	`见 [theme_item Label.font]。`	见 Label.font。
`[param name]` 格式化参数名称（作为代码）	`用 [param size] 来表示大小。`	用 `size` 表示大小。
`[br]` 换行	`行 1。[br]` `行 2。`	行 1。行 2。
`[b]` `[/b]` 粗体	`一些[b]粗体[/b]文本。`	一些粗体文本。
`[i]` `[/i]` 斜体	`一些[i]斜体[/i]文本。`	一些斜体文本。
`[kbd]` `[/kbd]` 键盘和鼠标快捷键	`一些 [kbd]Ctrl + C[/kbd] 按键。`	一些 `Ctrl + C` 按键。
`[code]` `[/code]` 等宽字体	`一些[code]等宽[/code]文本。`	一些`等宽`文本。
`[codeblock]` `[/codeblock]` 多行预格式化块	见下文.	见下文.

备注

目前只有 @GDScript 有注解。
从 [code] 开始禁用 BBCode ，直到文档解析器解析到 [/code] 。
从 [codeblock] 开始禁用 BBCode ，直到文档解析器解析到 [/codeblock] 。

警告

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

Previous Next

Built with Sphinx using a theme provided by Read the Docs.

GDScript 文档注释

GDScript 文档注释

为脚本编写文档

标记

为脚本类成员编写文档

标记

完整脚本示例

文档注释标记 @deprecated 和 @experimental

BBCode 与类参考

文档注释标记 `@deprecated` 和 `@experimental`