GDScript 文件註解

在 GDScript 中，註解可用於為你的程式碼撰寫說明文件，也能為腳本成員添加描述。普通註解和文件註解有兩個差異。首先，文件註解必須以雙井號 ## 開頭。其次，它必須緊接在腳本成員之前，或若是腳本說明則須放在腳本最上方。若有加上文件註解的匯出變數，其描述會在編輯器中顯示為工具提示。這些說明文件也可由編輯器匯出成 XML 檔案。

腳本文件撰寫方式

腳本說明文件註解必須寫在所有成員文件之前。建議的腳本說明格式可分三個部分。

腳本的簡短描述。
詳細描述。
教學連結，以及已棄用/實驗性註記。

為了分隔不同區塊，文件註解支援特殊標籤。標籤必須在行首（可忽略前導空白），格式為 @ 加上關鍵字。

標籤

簡要說明	無標籤。必須放在說明區塊的最開頭。
說明	無標籤。以一行空白分隔簡要與詳細描述。
教學	`@tutorial: https://example.com` `@tutorial(此處填寫標題): https://example.com`
已棄用	`@deprecated` `@deprecated: 請改用 [AnotherClass]。`
實驗性	`@experimental` `@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://example.com/tutorial_1
## @tutorial(Tutorial 2): https://example.com/tutorial_2
## @experimental

警告

若標籤名稱與冒號之間有空格（如 @tutorial :），則此標籤無效會被忽略。

備註

當描述跨多行時，前後空白會被移除並以單一空格串接。若要保留換行請使用 [br] 。可參考下方的 BBCode 與類別參考。

腳本成員文件化

可撰寫說明文件的成員有：

訊號
列舉
列舉值
常數
變數
函式
內部類別

腳本成員的文件註解必須緊接於該成員（或其註解）之前。描述可多行，但每行都必須以雙井號 ## 開頭才會被視為說明文件的一部分。

標籤

說明	無標籤。
已棄用	`@deprecated` `@deprecated: 請改用 [member another]。`
實驗性	`@experimental` `@experimental: 此方法尚未完成。`

例如：

## The description of the variable.
## @deprecated: Use [member other_var] instead.
var my_var

你也可以使用行內文件註解：

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

每當腳本更新時，說明文件會自動於編輯器的說明視窗中同步更新。若成員變數或函式名稱以底線開頭，將被視為私有成員，不會出現在文件裡，也不會顯示於說明視窗。

完整腳本範例

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

`@deprecated` 與 `@experimental` 標籤

你可以將類別或其任何成員標記為已棄用或實驗性，這樣在內建說明檢視器就會顯示對應的註記。也可以加上簡短說明，說明為何此 API 不建議使用。這對外掛或函式庫作者特別有幫助。

../../../_images/deprecated_and_experimental_tags.webp

已棄用 標記表示此 API 未來主要版本可能移除或有不相容更動，通常僅為向下相容而保留。
實驗性 標記表示此 API 尚不穩定，可能於目前主要分支中變更或移除。不建議於正式產品程式中使用。

備註

雖然技術上可以同時在同一類別/成員上標註 @deprecated 及 @experimental，但這不符合慣例，不建議這麼做。

BBCode 與類別參考

Godot 的類別參考支援類似 BBCode 的標籤，可讓文字有更好格式，同樣能用於腳本說明文件。詳見類別參考 BBCode。注意這與 RichTextLabel 的 BBCode 用法略有不同。

當你要連結到其他類別的成員時，需要寫上類別名稱。若是連結到同一類別的成員，類別名稱可省略。

可用標籤如下：

標籤與說明	範例	結果
`[Class]` 連結至類別	`移動 [Sprite2D]。`	移動 Sprite2D。
`[annotation Class.name]` 連結至註解	`請參閱 [annotation @GDScript.@rpc]。`	請參閱 @GDScript.@rpc。
`[constant Class.name]` 連結至常數	`請參閱 [constant Color.RED]。`	請參閱 Color.RED。
`[enum Class.name]` 連結至列舉	`請參閱 [enum Mesh.ArrayType]。`	請參閱 Mesh.ArrayType。
`[member Class.name]` 成員（屬性）連結	`取得 [member Node2D.scale]。`	取得 Node2D.scale。
`[method Class.name]` 連結至方法	`呼叫 [method Node3D.hide]。`	呼叫 Node3D.hide()。
`[constructor Class.name]` 連結至建構子	`使用 [constructor Color.Color]。`	使用 Color.Color。
`[operator Class.name]` 連結至運算子	`使用 [operator Color.operator *]。`	使用 Color.operator *。
`[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 行。
`[lb]` `[rb]` 分別為 `[` 與 `]`	`[lb]b[rb]text[lb]/b[rb]`	[b]text[/b]
`[b]` `[/b]` 粗體	`請[b]不要[/b]呼叫此方法。`	請不要呼叫此方法。
`[i]` `[/i]` 斜體	`回傳[i]全域[/i]座標。`	回傳全域座標。
`[u]` `[/u]` 底線	`[u]Always[/u] use this method.`	Always use this method.
`[s]` `[/s]` 刪除線	`[s]過時資訊。[/s]`	~~Outdated information.~~
`[color]` `[/color]` 顏色	`[color=red]Error![/color]`	Error!
`[font]` `[/font]` 字型	`[font=res://mono.ttf]LICENSE[/font]`	LICENSE
`[img]` `[/img]` 圖片	`[img width=32]res://icon.svg[/img]`
`[url]` `[/url]` 超連結	`[url]https://example.com[/url]` `[url=https://example.com]網站[/url]`	https://example.com 網站
`[center]` `[/center]` 水平置中	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` 鍵盤／滑鼠快捷鍵	`按下 [kbd]Ctrl + C[/kbd]。`	按下 `Ctrl + C`。
`[code]` `[/code]` 行內程式碼片段	`回傳 [code]true[/code]。`	回傳 `true`。
`[codeblock]` `[/codeblock]` 多行程式碼區塊	見下方。	見下方。

備註

目前僅 @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

預設情況下，[codeblock] 會高亮顯示 GDScript 語法。你可以透過 lang 屬性來更改，目前支援的選項有：

[codeblock lang=text] 不會進行語法高亮;
[codeblock lang=gdscript] 會高亮 GDScript 語法;
[codeblock lang=csharp] 會高亮 C# 語法（僅 .NET 版本適用）。