Внесок у довідку про клас

Class reference — це набір статей, що описують публічний API двигуна. Це включає описи для різних класів, методів, властивостей і глобальних об'єктів, доступних для сценаріїв. Посилання на клас доступне в Інтернеті на бічній панелі документації та в редакторі Godot у меню довідки.

У міру того, як рушій зростає, а функції додаються або змінюються, деякі частини посилання на клас стають застарілими, і потрібно додавати нові описи та приклади. Хоча розробники зобов’язані документувати свою роботу в довідці про клас під час подання запиту на отримання, ми не можемо очікувати, що кожен програміст буде хорошим технічним автором. Для таких співавторів, як ви, завжди є робота, щоб відшліфувати наявний і створити відсутній довідковий матеріал.

Джерело посилання на клас

Оскільки довідник класу доступний у двох місцях: онлайн і в редакторі, нам потрібно подбати про синхронізацію. Щоб досягти цього, основне сховище Godot вибрано як джерело правди, і там відстежується документація для посилання на клас.

Попередження

Ви не редагуєте файли .rst у папці classes/ репозиторію документації. Ці файли генеруються автоматично та синхронізуються вручну розробниками проекту. Читайте далі, щоб дізнатися, як правильно редагувати посилання на клас.

У головному репозиторії посилання на клас зберігається у файлах XML, по одному для кожного відкритого класу або глобального об’єкта. Більшість цих файлів розташовано в doc/classes/, але деякі модулі також містять власну документацію. Ви знайдете його в каталозі modules/<module_name>/doc_classes/. Щоб дізнатися більше про редагування файлів XML, зверніться до Базовий буквар класу.

Дивись також

Докладні відомості про використання Git і робочий процес запиту на отримання дивіться на сторінці Робочий процес запиту на отримання.

Якщо ви хочете перекласти посилання на клас з англійської на іншу мову, перегляньте Редактор і локалізація документації. Цей посібник також доступний як відеоурок на YouTube.

Важливо: Якщо ви плануєте внести великі зміни, вам слід створити проблему в репозиторії godot-docs або прокоментувати існуючу проблему. Це дасть іншим зрозуміти, що ви вже займаєтесь даним класом.

Що внести

Природним місцем для початку внеску є класи, які вам найкраще знайомі. Це гарантує, що доданий опис базуватиметься на досвіді та необхідному ноу-хау, а не лише на назві методу чи властивості. Радимо не додавати описи, які не потребують зусиль, як би привабливо це не виглядало. Такі описи приховують потребу в документації, і їх важко ідентифікувати автоматично.

Дивись також

Дотримання цього принципу є важливим і дозволяє нам створювати інструменти для учасників. Наприклад, трекер статусу завершення посилання на клас. Ви можете використовувати його для швидкого пошуку сторінок документації, на яких відсутні описи.

Якщо ви вирішили задокументувати клас, але не знаєте, що робить конкретний метод, не хвилюйтеся. Залиште це наразі та перелічіть методи, які ви пропустили, коли ви відкриваєте запит на вилучення зі своїми змінами. Про це подбає інший письменник.

You can still look at the methods' implementation in Godot's source code on GitHub. If you have doubts, feel free to ask on the Godot Forum and Godot Contributors Chat.

Попередження

Якщо ви не внесете незначних змін, як-от виправлення помилки, ми не рекомендуємо використовувати веб-редактор GitHub для редагування XML-файлів посилання на клас. Йому бракує функцій для належного редагування XML, як-от збереження узгодженості відступів, і він не дозволяє змінювати коміти на основі оглядів.

Це також не дозволяє перевірити ваші зміни в системі або за допомогою сценаріїв перевірки, як описано в Як редагувати XML класу.

Оновлення посилання на клас при роботі над двигуном

Коли ви створюєте новий клас або змінюєте API існуючого двигуна, вам потрібно повторно створити XML-файли в doc/classes/.

Для цього вам спочатку потрібно скомпілювати Godot. Перегляньте сторінку Знайомство з системою побудови, щоб дізнатися, як. Потім виконайте скомпільований двійковий файл Godot із кореневого каталогу Godot за допомогою параметра --doctool. Наприклад, якщо ви користуєтеся 64-бітною ОС Linux, командою може бути:

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

Точний набір суфіксів може бути іншим. Уважно прочитайте статтю за посиланням, щоб дізнатися більше про це.

Файли XML у doc/classes/ мають бути оновлені з поточними функціями Godot Engine. Потім ви можете перевірити, що змінилося, використовуючи команду git diff.

Будь ласка, включайте у свої коміти лише зміни, які стосуються вашої роботи над API. Ви можете відхилити зміни в інших XML-файлах за допомогою git checkout, але подумайте про те, щоб повідомити про це, якщо ви помітили оновлення непов’язаних файлів. В ідеалі виконання цієї команди має викликати лише ті зміни, які ви самі зробили.

Потім вам потрібно буде додати описи до будь-яких новостворених записів.