Up to date

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

GDScript Dokumentations-Kommentare¶

In GDScript können Kommentare verwendet werden, um Ihren Code zu dokumentieren und Beschreibungen zu den Membern eines Skripts hinzuzufügen. Es gibt zwei Unterschiede zwischen einem normalen Kommentar und einem Dokumentationskommentar. Erstens sollte ein Dokumentationskommentar mit doppelten Rautezeichen ## beginnen. Zweitens muss er unmittelbar vor einem Member des Skripts stehen bzw. bei Skriptbeschreibungen am Anfang des Skripts platziert werden. Wenn eine exportierte Variable dokumentiert ist, wird ihre Beschreibung als Tooltip im Editor verwendet. Diese Dokumentation kann vom Editor als XML-Datei erzeugt werden.

Dokumentieren eines Skripts¶

Kommentare, die ein Skript dokumentieren, müssen vor jeder Member-Dokumentation stehen. Ein empfohlenes Format für die Skriptdokumentation kann in drei Teile unterteilt werden.

Eine kurze Beschreibung des Skripts.
Detaillierte Beschreibung.
Tutorials und Kennzeichnungen für veralteten/experimentellen Code.

Um diese voneinander zu trennen, verwenden die Dokumentationskommentare spezielle Tags. Die Markierung muss am Anfang einer Zeile stehen (vorangehende Leerzeichen werden ignoriert) und das Format @ haben, gefolgt von dem Schlüsselwort.

Tags¶

Kurzbeschreibung	Kein Tag. Steht ganz am Anfang des Dokumentationsabschnitts.
Beschreibung	Kein Tag. Verwenden Sie eine Leerzeile, um die Beschreibung von der Kurzbeschreibung zu trennen.
Tutorial	`@tutorial:` `@tutorial(Titel Einfügen):`
Veraltet	`@deprecated`
Experimentell	`@experimental`

Zum Beispiel:

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

Warnung

Wenn zwischen dem Tag-Namen und dem Doppelpunkt ein Leerzeichen steht, z.B. @tutorial :, wird es nicht als gültiger Tag behandelt und ignoriert.

Bemerkung

Wenn sich die Beschreibung über mehrere Zeilen erstreckt, werden die vorangehenden und nachfolgenden Leerzeichen entfernt und durch ein einziges Leerzeichen ersetzt. Um den Zeilenumbruch beizubehalten, verwenden Sie [br]. Siehe auch BBCode und Klassenreferenz unten.

Dokumentieren von Skript-Membern¶

Member, die für die Dokumentation in Frage kommen:

Innere Klasse
Konstante
Funktion
Signal
Variable
Enum
Enum-Wert

Die Dokumentation eines Skript-Members muss unmittelbar vor dem Member oder seinen Annotationen stehen, falls es welche hat. Die Beschreibung kann mehr als eine Zeile haben, aber jede Zeile muss mit dem doppelten Rautezeichen ## beginnen, um als Teil der Dokumentation zu gelten.

Tags¶

Beschreibung	Kein Tag.
Veraltet	`@deprecated`
Experimentell	`@experimental`

Zum Beispiel:

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

Alternativ können Sie auch Inline-Dokumentationskommentare verwenden:

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

Die Skriptdokumentation wird bei jeder Aktualisierung des Skripts im Hilfefenster des Editors aktualisiert. Wenn eine Member-Variable oder ein Funktionsname mit einem Unterstrich beginnt, wird sie als privat behandelt. Er erscheint nicht in der Dokumentation und wird im Hilfefenster ignoriert.

Vollständiges Skript-Beispiel¶

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 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` und``@experimental``-Tags ¶

Sie können eine Klasse oder einen ihrer Member als veraltet oder experimentell markieren. Dadurch wird der entsprechende Indikator in der integrierten Dokumentationsanzeige hinzugefügt. Dies kann besonders für die Entwickler von Plugins und Bibliotheken nützlich sein.

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

Veraltet kennzeichnet eine nicht empfohlene API, die in einem zukünftigen Release entfernt werden oder eine inkompatible Änderung erfahren soll. Normalerweise wird die API aus Gründen der Abwärtskompatibilität beibehalten.
Experimentell kennzeichnet eine neue, instabile API, die im aktuellen Hauptzweig geändert oder entfernt werden kann. Die Verwendung dieser API wird im Produktionscode nicht empfohlen.

Bemerkung

Obwohl Sie technisch gesehen sowohl @deprecated als auch @experimental für dieselbe Klasse/denselben Member verwenden können, wird dies nicht empfohlen, da es gegen die üblichen Konventionen verstößt.

BBCode und Klassenreferenz¶

Das Hilfefenster des Editors, das die Dokumentation anzeigt, unterstützt bbcode. Dadurch ist es möglich, die Dokumentation auszurichten und zu formatieren. Farbige Texte, Bilder, Schriftarten, Tabellen, URLs, Animationseffekte, etc. können mit dem bbcode hinzugefügt werden.

Die Klassenreferenz von Godot unterstützt BBCode-ähnliche Tags. Sie fügen dem Text eine hübsche Formatierung hinzu, die auch in der Dokumentation verwendet werden kann. Siehe auch Klassenreferenz bbcode.

Wenn Sie auf einen Member einer anderen Klasse verweisen, müssen Sie den Klassennamen angeben. Bei Verweisen auf dieselbe Klasse ist der Klassenname optional und kann weggelassen werden.

Hier ist die Liste der verfügbaren Tags:

Tag und Beschreibung	Beispiel	Ergebnis
`[Class]` Link zur Klasse	`Move the [Sprite2D].`	Move the Sprite2D.
`[annotation Class.name]` Link zur Annotation	`See [annotation @GDScript.@export].`	See @GDScript.@export.
`[constant Class.name]` Link zur Konstante	`See [constant @GlobalScope.KEY_F1].`	See @GlobalScope.KEY_F1.
`[enum Class.name]` Link zum Enum	`See [enum Mesh.ArrayType].`	See Mesh.ArrayType.
`[method Class.name]` Link zur Methode	`Call [method Node3D.hide].`	Call Node3D.hide().
`[member Class.name]` Link zum Member	`Get [member Node2D.scale].`	Get Node2D.scale.
`[signal Class.name]` Link zum Signal	`Emit [signal Node.renamed].`	Emit Node.renamed.
`[theme_item Class.name]` Link zum Theme-Element	`See [theme_item Label.font].`	See Label.font.
`[param name]` Formatiert einen Parameter-Namen (als Code)	`Takes [param size] for the size.`	Takes `size` for the size.
`[br]` Zeilenumbruch	`Line 1.[br]` `Line 2.`	Line 1. Line 2.
`[b]` `[/b]` Fett	`Some [b]bold[/b] text.`	Some bold text.
`[i]` `[/i]` Kursiv	`Some [i]italic[/i] text.`	Some italic text.
`[kbd]` `[/kbd]` Tasten/Maus-Kürzel	`Some [kbd]Ctrl + C[/kbd] key.`	Some `Ctrl + C` key.
`[code]` `[/code]` Monospace	`Some [code]monospace[/code] text.`	Some `monospace` text.
`[codeblock]` `[/codeblock]` Mehrzeiliger vorformatierter Block	Siehe unten	Siehe unten

Bemerkung

Aktuell verfügt nur @GDScript über Annotationen.
[code] deaktiviert BBCode, bis der Parser auf [/code] trifft.
[codeblock] deaktiviert BBCode, bis der Parser auf [/codeblock] trifft.

Warnung

Verwenden Sie [codeblock] für vorformatierte Codeblöcke. Verwenden Sie in [codeblock] immer vier Leerzeichen zum Einrücken (der Parser löscht Tabs).

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

GDScript Dokumentations-Kommentare¶

Dokumentieren eines Skripts¶

Tags¶

Dokumentieren von Skript-Membern¶

Tags¶

Vollständiges Skript-Beispiel¶

@deprecated und``@experimental``-Tags¶

BBCode und Klassenreferenz¶

`@deprecated` und``@experimental``-Tags ¶