Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
撰寫自定說明文件
在 GDScript 中,註解可用於記錄程式碼並為腳本成員新增描述。普通註釋和文件註釋之間有兩個區別。首先,文件註解應以雙散列符號「##」開頭。其次,它必須緊接在腳本成員之前,或者對於腳本描述,應放置在腳本的頂部。如果記錄了匯出的變量,則其描述將用作編輯器中的工具提示。該檔案可以由編輯器產生為 XML 檔案。
執行腳本
記錄腳本的註解必須位於任何成員檔案之前。腳本檔案的建議格式可以分為三個部分。
資源的文字描述.
說明
教學和已放棄使用/實驗標記。
為了將它們彼此分開,檔案註釋使用特殊標籤。標記必須位於行的開頭(忽略前面的空格),並且必須採用格式“@”,後面跟著關鍵字。
建立腳本樣板
適用於檔案的成員:
訊號
Enum 列舉型別
列舉值
常數
變數
函式
內類別
腳本成員的文件必須緊接在該成員或其註解(如果有)之前。描述可以有多於一行,但每一行必須以雙井號「##」開頭才能被視為檔案的一部分。
標籤
說明 |
沒有標籤。 |
重複 |
@deprecated @deprecated: Use [member another] instead. |
實驗性 |
@experimental @experimental: This method is incomplete. |
如:
## The description of the variable.
## @deprecated: Use [member other_var] instead.
var my_var
Alternatively, you can use inline documentation comments:
signal my_signal ## My signal.
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.
func my_func(): ## My func.
pass
class MyClass: ## My class.
pass
每次更新腳本時,腳本檔案都會在編輯器說明視窗中更新。如果任何成員變數或函式名稱以下劃線開頭,它將被視為私有。它不會出現在檔案中,並且在說明視窗中將被忽略。
GDScript 範例
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://example.com/tutorial_1
## @tutorial(Tutorial 2): https://example.com/tutorial_2
## @experimental
## 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://example.com/tutorial
## @experimental
class Inner:
## Inner class variable v4.
var v4
## Inner class function fn.
func fn(): pass
類別參照手冊
Godot's class reference supports BBCode-like tags. They add nice formatting to the text which could also
be used in the documentation. See also class reference bbcode.
Note that this is slightly different from the RichTextLabel
BBCode.
每當連結到另一個類別的成員時,都需要指定類別名稱。對於指向同一類別的鏈接,類別名稱是可選的並且可以省略。
有六種搜尋模式:
說明 |
範例 |
結果 |
---|---|---|
[Class] 類別連結
|
移動 [Sprite]。 |
移動 class_sprite。 |
[註解類別名] 另一個類別的方法連結
|
|
See @GDScript.@rpc. |
[signal 類別.訊號名稱]
定義一個常數。
|
|
See Color.RED. |
[member 類別.成員名稱]
同意授權條款
|
|
請參閱:ref:Mesh.ArrayType <enum_Mesh_ArrayType>。 |
[member 類別.成員名稱]
Link to member (property)
|
取得 [member Node2D.scale]。 |
取得 scale 。 |
[method 類別.方法名稱]
繫結方法
|
呼叫 [method hide]。 |
參考 hide 。 |
[constructor Class.name] Link to built-in constructor
|
|
Use Color.Color. |
[operator Class.name] Link to built-in operator
|
|
Use Color.operator *. |
[signal 類別.訊號名稱]
繫結訊號
|
發送 [signal Node.renamed]。 |
發送 renamed。 |
[method 類別.方法名稱]
同意授權條款
|
|
請參閱:ref:Label.font <class_Label_theme_font_font>。 |
name Parameter name (as code)
|
“採用 [param size] 作為大小。” |
採用“size”作為尺寸。 |
[br] break
|
第 1 行。[br] 第 2 行。 |
1號線。
2號線。
|
[lb] [rb] [ and ] respectively |
|
[b]text[/b] |
[b] [/b]
粗體
|
|
Do not call this method. |
[i] [/i]
斜體
|
|
Returns the global position. |
[u] [/u] Underline
|
|
Always use this method. |
[s] [/s] Strikethrough
|
|
|
[color] [/color] 顏色
|
|
Error! |
[font] [/font] Font
|
|
LICENSE |
[img] [/img] Image
|
|
|
[url] [/url] Hyperlink
|
[url]https://example.com[/url] [url=https://example.com]Website[/url] |
|
[center] [/center] Horizontal centering
|
|
|
[kbd] [/kbd] 鍵盤或滑鼠快捷鍵
|
|
Press Ctrl + C. |
[code] [/code] Inline code fragment
|
|
Returns |
[codeblock] [/codeblock] Multiline code block
|
參見下方。 |
參見下方。 |
備註
目前只有 @GDScript 有注解。
[kbd]
停用 BBCode,直到解析器遇到[/kbd]
。[code]
停用 BBCode,直到解析器遇到[/code]
。[codeblock]
停用 BBCode,直到解析器遇到[/codeblock]
。
警告
使用 [codeblock]
來標記預先格式化的程式碼區塊。在 [codeblock]
中,請務必使用 四個空格 來進行縮排 (剖析器會移除 Tab 字元)。例如:
## 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
By default, [codeblock]
highlights GDScript syntax. You can change it using
the lang
attribute. Currently supported options are:
[codeblock lang=text]
disables syntax highlighting;[codeblock lang=gdscript]
highlights GDScript syntax;[codeblock lang=csharp]
highlights C# syntax (only in .NET version).