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
У GDScript коментарі можна використовувати для документування вашого коду та додавання описів до членів сценарію. Є дві відмінності між звичайним коментарем і коментарем документації. По-перше, коментар до документації має починатися з подвійних символів ##. По-друге, він має передувати безпосередньо члену сценарію або, для описів сценарію, розміщуватися у верхній частині сценарію. Якщо експортована змінна задокументована, її опис використовується як підказка в редакторі. Ця документація може бути згенерована редактором у вигляді файлів XML.
Документування сценарію
Коментарі, що документують скрипт, мають бути перед будь-якою документацією учасників. Пропонований формат документації скрипта можна розділити на три частини.
Короткий опис сценарію.
Детальний опис.
Підручники та застарілі/експериментальні оцінки.
Щоб відокремити їх один від одного, коментарі до документації використовують спеціальні теги. Тег має бути на початку рядка (не враховуючи пробіли перед ним) і мати формат @, після якого йде ключове слово.
Документування учасників сценарію
Члени, які застосовуються для документації:
Сигнал
Enum
Значення Enum
Constant
Variable
Function
Внутрішній клас
Документація елемента сценарію повинна безпосередньо передувати члену або його анотаціям, якщо вони є. Опис може мати більше одного рядка, але кожен рядок має починатися з символу подвійної решітки ##, щоб вважатися частиною документації.
Теги
Опис |
Без тегу. |
Застаріле |
@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 не рекомендується. Це може бути особливо корисним для творців плагінів і бібліотек.
Застарілий позначає нерекомендований API, який підлягає видаленню або несумісним змінам у майбутньому основному випуску. Зазвичай API зберігається для зворотної сумісності.
Експериментальний позначає новий нестабільний API, який можна змінити або видалити в поточній основній гілці. Не рекомендується використовувати цей API у робочому коді.
Примітка
Хоча технічно ви можете використовувати теги @deprecated і @experimental для того самого класу/члена, це не рекомендується, оскільки це суперечить загальним умовам.
BBCode та посилання на клас
Посилання на клас Godot підтримує теги, подібні до BBCode. Вони додають приємне форматування тексту, який також можна використовувати в документації. Дивіться також class reference bbcode. Зауважте, що це дещо відрізняється від RichTextLabel BBCode.
Щоразу, коли ви посилаєтеся на члена іншого класу, вам потрібно вказати назву класу. Для посилань на той самий клас ім’я класу є необов’язковим і його можна опустити.
Ось список доступних тегів:
Тег і опис |
Приклад |
Результат |
|---|---|---|
[Class]Посилання на клас
|
|
Перемістити class_Sprite2D. |
[annotation Class.name]Посилання на анотацію
|
|
Перегляньте @GDScript.@rpc. |
[constant Class.name]Посилання на константу
|
|
Перегляньте Color.RED. |
[enum Class.name]Посилання на enum
|
|
Див. Mesh.ArrayType. |
[member Class.name]Посилання на учасника (власність)
|
|
Отримати Node2D.scale. |
[method Class.name]Посилання на метод
|
|
Виклик Node3D.hide(). |
[constructor Class.name]Посилання на вбудований конструктор
|
|
Використовуйте Color.Color. |
[operator Class.name]Посилання на вбудований оператор
|
|
Використовуйте Color.operator *. |
[сигнал Class.name]Посилання на сигнал
|
|
Видати Node.renamed. |
[theme_item Class.name]Посилання на предмет теми
|
|
Перегляньте Label.font. |
[param name]Назва параметра (як код)
|
|
Використовує |
[br]Розрив рядка
|
Line 1.[br]Line 2. |
Рядок 1.
Рядок 2.
|
[lb] [rb][ і ] відповідно |
|
[b]text[/b] |
[b] [/b]Напівжирний
|
|
Не викликайте цей метод. |
[i] [/i]Курсив
|
|
Повертає глобальну позицію. |
[u] [/u]Підкреслити
|
|
Always use this method. |
[s] [/s]Закреслення
|
|
|
[color] [/color]Колір
|
|
Error! |
[font] [/font]Шрифт
|
|
LICENSE |
[img] [/img]Зображення
|
|
|
[url] [/url]Гіперболічний синус
|
[url]https://example.com[/url][url=https://example.com]Website[/url] |
|
[center] [/center]Горизонтальне центрування
|
|
|
[kbd] [/kbd]Комбінація клавіш/миші
|
|
Натисніть Ctrl + C. |
[code] [/code]Вбудований фрагмент коду
|
|
Повертає |
[codeblock][/codeblock]Багаторядковий кодовий блок
|
Див. нижче. |
Див. нижче. |
Примітка
Наразі лише @GDScript має анотації.
[kbd]вимикає BBCode, поки аналізатор не зустріне[/kbd].[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
За замовчуванням [codeblock] підсвічує синтаксис GDScript. Ви можете змінити його за допомогою атрибута lang. Наразі підтримуються такі варіанти:
[codeblock lang=text]вимикає підсвічування синтаксису;[codeblock lang=gdscript]підсвічує синтаксис GDScript;[codeblock lang=csharp]підсвічує синтаксис C# (лише у версії .NET).