Up to date

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

Beitragen zur Klassenreferenz

Die Klassenreferenz ist eine Sammlung von Artikeln zur Beschreibung der public Engine-API. Dazu gehören Beschreibungen für verschiedene Klassen, Methoden, Propertys und globale Objekte, die für die Skripterstellung zur Verfügung stehen. Die Klassenreferenz ist online über die Seitenleiste der Dokumentation und im Godot-Editor über das Hilfemenü verfügbar.

Wenn die Engine wächst und Features hinzugefügt oder verändert werden, werden einige Teile der Klassenreferenz veraltet und neue Beschreibungen und Beispiele müssen hinzugefügt werden. Während Entwickler dazu angehalten sind, ihre gesamte Arbeit in der Klassenreferenz zu dokumentieren, wenn sie einen Pull Request einreichen, können wir nicht erwarten, dass jeder in der Lage ist, eine qualitativ hochwertige Dokumentation zu schreiben.

Die Quelle der Klassenreferenz

Da die Klassenreferenz an zwei Stellen verfügbar ist, nämlich online und im Editor, müssen wir dafür sorgen, dass die Dinge synchron bleiben. Um dies zu erreichen, wird das Godot-Hauptrepository als Quelle der Wahrheit gewählt, und die Dokumentation für die Klassenreferenz wird dort nachverfolgt.

Warnung

Sie sollten nicht die .rst-Dateien im classes/-Ordner des Documentations-Repository bearbeiten. Diese Dateien werden automatisch generiert und werden von den Projekt-Maintainern manuell synchronisiert. Lesen Sie weiter, um zu erfahren, wie Sie die Klassenreferenz korrekt bearbeiten können.

Im Haupt-Repository wird die Klassenreferenz in XML-Dateien gespeichert, eine Datei für jede von außen zugreifbare Klasse oder jedes globale Objekt. Die meisten dieser Dateien befinden sich in doc/classes/, aber einige Module enthalten auch ihre eigene Dokumentation. Sie finden sie im Verzeichnis modules/<module_name>/doc_classes/. Um mehr über die Bearbeitung von XML-Dateien zu erfahren, lesen Sie Einführung in die Klassenreferenz.

Siehe auch

Für Erläuterungen zum Umgang mit Git und dem Workflow beim Pull Request, sehen Sie sich die Workflow eines Pull Requests-Seite an.

Wenn Sie die Klassenreferenz vom Englischen in eine andere Sprache übersetzen wollen, lesen Sie Editor und Dokumentation übersetzen. Diese Anleitung ist auch als Video-Tutorial auf YouTube verfügbar.

Wichtig: Wenn Sie vorhaben, größere Änderungen vorzunehmen, sollten Sie einen Eintrag im godot-docs-Repository erstellen oder einen Kommentar zu einem bestehenden Eintrag abgeben. Auf diese Weise können andere erfahren, dass Sie sich bereits um eine bestimmte Klasse kümmern.

Was Sie beitragen können

Am besten beginnen Sie mit den Klassen, mit denen Sie am besten vertraut sind. Dadurch wird sichergestellt, dass die hinzugefügte Beschreibung auf Erfahrung und dem notwendigen Know-how beruht und nicht nur auf dem Namen einer Methode oder einer Property. Wir raten davon ab, Beschreibungen mit geringem Aufwand hinzuzufügen, egal wie ansprechend sie auch aussehen mögen. Solche Beschreibungen verschleiern den Dokumentationsbedarf und sind schwer automatisch zu erkennen.

Siehe auch

Die Einhaltung dieses Grundsatzes ist wichtig und ermöglicht es uns, Werkzeuge für die Mitwirkenden zu schaffen. Wie zum Beispiel der completion status tracker der Klassenreferenz. Sie können ihn verwenden, um schnell Dokumentationsseiten zu finden, denen Beschreibungen fehlen.

Wenn Sie sich entscheiden, eine Klasse zu dokumentieren, aber nicht wissen, was eine bestimmte Methode tut, machen Sie sich keine Sorgen. Lassen Sie es vorerst und listen Sie die Methoden auf, die Sie übersprungen haben, wenn Sie einen Pull Request mit Ihren Änderungen erstellen. Ein anderer Autor wird sich darum kümmern.

Sie können sich die Implementierung der Methoden im Quellcode von Godot auf GitHub ansehen. Wenn Sie Zweifel haben, können Sie auf der Q&A Website und im Godot Mitwirkenden-Chat fragen.

Warnung

Sofern Sie keine kleineren Änderungen vornehmen, wie z.B. das Korrigieren eines Tippfehlers, empfehlen wir nicht, den GitHub Webeditor zum Bearbeiten der XML-Dateien der Klassenreferenz zu verwenden. Ihm fehlen Features, um XML gut zu bearbeiten, wie z.B. Einrückungen konsistent zu halten, und er erlaubt es nicht, Commits auf der Grundlage von Reviews zu ändern.

Es erlaubt Ihnen auch nicht, Ihre Änderungen in der Engine oder mit Validierungsskripten zu testen, wie in Wie man Klassen-XMLs bearbeitet beschrieben.

Aktualisierung der Klassenreferenz bei Arbeiten an der Engine

Wenn Sie eine neue Klasse erstellen oder die API einer bestehenden Engine ändern, müssen Sie die XML-Dateien in doc/classes/ neu generieren.

Dazu müssen Sie zunächst Godot kompilieren. Siehe die Seite Einführung in das Buildsystem, um zu erfahren, wie. Dann führen Sie die kompilierte Godot-Binärdatei aus dem Godot-Stammverzeichnis mit der Option --doctool aus. Wenn Sie zum Beispiel ein 64-Bit-Linux verwenden, könnte der Befehl lauten:

./bin/godot.linuxbsd.editor.x86_64 --doctool

Die exakte Menge von Suffixen kann unterschiedlich sein. Lesen Sie den verlinkten Artikel sorgfältig durch, um mehr darüber zu erfahren.

Die XML-Dateien in doc/classes/ sollten dann auf dem aktuellen Stand der Godot-Engine-Features sein. Sie können dann mit dem Befehl git diff überprüfen, was sich geändert hat.

Bitte nehmen Sie nur Änderungen in Ihre Commits auf, die für Ihre Arbeit an der API relevant sind. Sie können Änderungen in anderen XML-Dateien mit git checkout verwerfen, aber Sie sollten es melden, wenn Sie feststellen, dass nicht verwandte Dateien aktualisiert wurden. Idealerweise sollte dieser Befehl nur die Änderungen anzeigen, die Sie selbst vorgenommen haben.