Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

撰寫自定說明文件¶

在 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 和類別參考”。

建立腳本樣板¶

適用於檔案的成員：

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

腳本成員的文件必須緊接在該成員或其註解（如果有）之前。描述可以有多於一行，但每一行必須以雙井號「##」開頭才能被視為檔案的一部分。

標籤¶

說明	沒有標籤。
重複	`@deprecated`
實驗性	`@experimental`

如：

## The description of the variable.
## @deprecated
var my_var

Alternatively, you can use inline documentation comments:

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

每次更新腳本時，腳本檔案都會在編輯器說明視窗中更新。如果任何成員變數或函式名稱以下劃線開頭，它將被視為私有。它不會出現在檔案中，並且在說明視窗中將被忽略。

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://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` 標籤¶

您可以將類別或其任何成員標記為已放棄使用或實驗性的。這將在內建檔案檢視器中新增相應的指標。這對於插件和庫建立者特別有用。

../../../_images/deprecated_and_experimental_marks.webp

已放棄使用 標記不建議的 API，可能會在未來的主要版本中刪除或進行不相容的更改。通常保留 API 是為了向後相容。
**實驗性**旗標著一個新的不穩定 API，可能會在目前主要分支中變更或刪除。不建議在生產程式碼中使用此 API。

備註

雖然從技術上講，您可以在同一類/成員上使用“@deprecated”和“@experimental”標籤，但不建議這樣做，因為它違反了常見約定。

類別參照手冊¶

顯示文件的編輯器幫助視窗支援:ref:bbcode <doc_bbcode_in_richtextlabel>。因此，可以對齊和格式化文件。彩色文字、圖像、字型、表格、URL、動畫效果等可以使用 bbcode 新增。

Godot 的類別參照文件支援類似 BBCode 的標籤。這些標籤可以為文字加上格式。下面列出了所有可用的標籤：

每當連結到另一個類別的成員時，都需要指定類別名稱。對於指向同一類別的鏈接，類別名稱是可選的並且可以省略。

有六種搜尋模式：

說明	範例	結果
`[Class]` 類別連結	移動 [Sprite]。	移動 class_sprite。
`[註解類別名]` 另一個類別的方法連結	`請參閱[註釋@GDScript.@export]。`	請參閱:ref:@GDScript.@export <class_@GDScript_annotation_@export>。
[signal 類別.訊號名稱] 定義一個常數。	`請參閱[常數@GlobalScope.KEY_F1]。`	請參閱:ref:@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>。
[member 類別.成員名稱] 同意授權條款	`參見[列舉Mesh.ArrayType]。`	請參閱:ref:Mesh.ArrayType <enum_Mesh_ArrayType>。
[method 類別.方法名稱] 繫結方法	呼叫 [method hide]。	參考 hide 。
[member 類別.成員名稱] 編輯成員	取得 [member Node2D.scale]。	取得 scale 。
[signal 類別.訊號名稱] 繫結訊號	發送 [signal Node.renamed]。	發送 renamed。
[method 類別.方法名稱] 同意授權條款	`參見[theme_item Label.font]。`	請參閱:ref:Label.font <class_Label_theme_font_font>。
`name` 格式化參數名稱（作為程式碼）	“採用 [param size] 作為大小。”	採用“size”作為尺寸。
`[br]` break	`第 1 行。[br]` `第 2 行。`	1號線。 2號線。
[b] [/b] 粗體	普通的 [b]粗體[/b] 文字。	普通的粗體文字。
[i] [/i] 斜體	普通的 [i]斜體[/i] 文字。	普通的斜體文字。
`[kbd]` `[/kbd]` 鍵盤或滑鼠快捷鍵	普通的 [kbd]Ctrl + C[/kbd] 按鍵。	普通的 `Ctrl + C` 按鍵。
`[code]` `[/code]` 等寬字形	普通的 [code]等寬字形 (Monospace)[/code] 文字。	普通的 `等寬字形 (Monospace)` 文字。
`[codeblock]` `[/codeblock]` 多行預格式化區塊	參見下方。	參見下方。

備註

目前只有 @GDScript 有注解。
[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