Комментарии к документации GDScript

В GDScript комментарии можно использовать для документирования кода и добавления описаний к элементам скрипта. Существует два различия между обычным комментарием и комментарием документации. Во-первых, комментарий документации должен начинаться с двух символов ##. Во-вторых, он должен непосредственно предшествовать элементу скрипта, а в случае описания скрипта — располагаться в начале скрипта. Если экспортируемая переменная документирована, её описание используется в качестве подсказки в редакторе. Редактор может генерировать эту документацию в виде XML-файлов.

Документирование скрипта

Комментарии, описывающие скрипт, должны быть размещены до любой документации участника. Рекомендуемый формат документации скрипта можно разделить на три части.

Краткое описание скрипта.
Подробное описание.
Учебные пособия и устаревшие/экспериментальные отметки.

Чтобы отделить их друг от друга, в комментариях к документации используются специальные теги. Тег должен располагаться в начале строки (без учёта предшествующих пробелов) и иметь формат @, за которым следует ключевое слово.

Теги

Краткое описание	Тега нет. Находится в самом начале раздела документации.
Описание	Без тега. Отделите описание от краткого содержания одной пустой строкой.
Учебное пособие	`@tutorial: https://example.com` `@tutorial(The Title Here): 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 и справочник классов ниже.

Документирование элементов скрипта

Элементы, имеющие отношение к документации:

Сигнал
Перечисление
Значение Перечисления (Enum)
Константа
Переменная
Функция
Внутренний класс

Документация элемента скрипта должна располагаться непосредственно перед самим элементом или его аннотациями, если таковые имеются. Описание может состоять из нескольких строк, но каждая строка должна начинаться с двух символов ##, чтобы считаться частью документации.

Теги

Описание	Нет тега.
Устаревший	`@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

Deprecated обозначает нерекомендуемый API, который может быть удалён или стать несовместимым в будущем крупном выпуске. Обычно API сохраняется для обеспечения обратной совместимости.
Experimental обозначает новый нестабильный API, который может быть изменён или удалён в текущей основной ветке. Использование этого API в рабочем коде не рекомендуется.

Примечание

Хотя технически вы можете использовать оба тега @deprecated и @experimental в одном классе/члене, это не рекомендуется, поскольку противоречит общепринятым соглашениям.

BBCode и ссылка на класс

Ссылка на класс Godot поддерживает теги, похожие на BBCode. Они добавляют удобное форматирование к тексту, которое также можно использовать в документации. См. также class reference 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]` Перенос строки	`Line 1.[br]` `Line 2.`	Строка 1. Строка 2.
`[lb]` `[rb]` `[` and `]` соответственно	`[lb]b[rb]text[lb]/b[rb]`	[b]text[/b]
`[b]` `[/b]` Жирный	`[b]Не[/b] вызывайте этот метод.`	Не вызывайте этот метод.
`[i]` `[/i]` Italic	`Возвращает [i]глобальную[/i] позицию.`	Возвращает глобальную позицию.
`[u]` `[/u]` Подчеркнуть	`[u]Всегда[/u] используйте этот метод.`	Always use this method.
`[s]` `[/s]` Зачеркивание	`[s]Устаревшая информация.[/s]`	~~Outdated information.~~
`[color]` `[/color]` Цвет	`[color=red]Error![/color]`	Error!
`[font]` `[/font]` Шрифт	`[font=res://mono.ttf]ЛИЦЕНЗИЯ[/font]`	LICENSE
`[img]` `[/img]` Изображение	`[img width=32]res://icon.svg[/img]`
`[url]` `[/url]` Гиперссылка	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Website
`[center]` `[/center]` Горизонтальное центрирование	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Сочетание клавиш/мыши	`Press [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] всегда используйте четыре пробела для отступа (анализатор удалит табуляции).

## 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).

Комментарии к документации GDScript

Документирование скрипта

Теги

Документирование элементов скрипта

Теги

Полный пример скрипта

Теги @deprecated и @experimental

BBCode и ссылка на класс

Теги `@deprecated` и `@experimental`