C#-справочник: чтение и правки — документация

Поиск объявления, перегрузки, аргументы, значения по умолчанию и правильное место для правки описаний.

Найти нужное объявление

Ищите точное имя C# вместе с типом: Rect2.Intersects, Entity.GetEntity<T>(), new Vector3(1, 2, 3). Справочник также ищет по описанию задачи, аргументов и результата. Поиск по всему порталу и фильтр «Поиск внутри класса» решают разные задачи: фильтр страницы сопоставляет имена и сигнатуры, а не весь текст описаний.

Наследуемый метод может находиться на странице базового типа. Например, поиск Button.QueueFree ведёт к объявлению Entity.QueueFree. Это не отсутствие метода у Button. На странице типа смотрите строку «Наследует» и переходите по ссылке на базовый тип.

Раскройте имя метода, затем выберите нужную перегрузку. Ссылка # рядом с конкретным объявлением содержит якорь именно этой перегрузки. Сохраняйте её целиком, если отправляете пример другому разработчику. Переключение языка не меняет имена C#.

Читать сигнатуру

Объявление из Rect2.Intersects:

C#
public bool Intersects(Rect2 b, bool includeBorders = false);

Это описание API, а не готовое тело метода для вставки в скрипт.

Часть	Как читать
`public`	Метод доступен вашему C#-коду.
`bool` перед именем	Возвращает `true` или `false`; прочитайте условия результата ниже сигнатуры.
`Intersects`	Имя метода с точным регистром.
`Rect2 b`	Обязательный аргумент типа Rect2. Его имя здесь — `b`, не выдуманное `other`.
`bool includeBorders = false`	Необязательный аргумент: при пропуске используется `false`. Именованный вызов — `includeBorders: true`.
`Area { get; }`	Свойство только для чтения; ему нельзя присвоить новое значение.
`Position { get; set; }`	Свойство можно читать и изменять.
`static` в другом объявлении	Член вызывается через имя типа. Отсутствие static обычно означает работу с экземпляром.
`?` у ссылочного типа	Аннотация допустимости null; это не автоматическая проверка значения во время выполнения.

Знак — в колонке значений по умолчанию означает, что значение по умолчанию не задано, а не то, что нужно передать null. Число и порядок аргументов определяются выбранной перегрузкой. Конструктор создаёт значение через new; void означает отсутствие возвращаемого значения.

Проверить поведение, а не только название

У прямоугольников с общей стороной обычный Intersects() даёт false, а Intersects(..., includeBorders: true) — true. Включение точки через HasPoint() имеет собственные правила границ. По названию Expand нельзя заключить, что HasPoint после него обязательно включит исходную точку.

Этот полный пример проверяет сразу обе ситуации:

C#
using Reckfell;

public static class RectangleExamples
{
    public static bool Validate()
    {
        var bounds = new Rect2(0, 0, 2, 2);
        var neighbor = new Rect2(2, 0, 2, 2);
        bool excludesEnd = !bounds.HasPoint(bounds.End);
        bool touches = bounds.Intersects(neighbor, includeBorders: true);
        bool overlaps = bounds.Intersects(neighbor);
        var cells = new Rect2I(0, 0, 2, 2);
        var cell = new Vector2I(2, 1);
        bool expandStillExcludes = !cells.Expand(cell).HasPoint(cell);
        Rect2I withCell = cells.Merge(new Rect2I(cell, Vector2I.One));
        return excludesEnd && touches && !overlaps
            && expandStillExcludes && withCell.HasPoint(cell)
            && withCell.Size == new Vector2I(3, 2);
    }
}

Добавьте файл RectangleExamples.cs в C#-проект. Вызов RectangleExamples.Validate() возвращает true при соблюдении показанных правил. Пример выполнен на установленной SDK 1.0.0. Это проверка методов структур, не отрисовки и не обработки мыши в Control.

Перед использованием метода прочитайте ограничения, систему координат и единицы. Уточните, меняет ли он объект или возвращает копию. Например, Rect2.Grow возвращает новое значение; отброшенный результат не расширит исходную переменную. Для NaN и бесконечностей проверяйте конечность данных отдельно. Для ресурсов и Entity также важны время жизни и допустимый момент обращения: одинаковый возвращаемый тип сам по себе не доказывает готовность GPU или наличие объекта в дереве.

Что подтверждает отметка SDK

«Объявления сверены с C# SDK» означает, что типы, сигнатуры, перегрузки и значения аргументов взяты из установленной SDK указанной версии. Эта отметка не подтверждает каждое предложение описания, все примеры, каждую платформу или качество изображения. Перевод, компиляция и проверка ссылок также не заменяют проверку поведения.

Если вызов из справочника не компилируется, сначала проверьте версию используемой SDK, пространство имён, выбранную перегрузку и точный регистр. Не заменяйте имя C# приблизительным переводом или автоматическим переводом snake_case в PascalCase.

Где исправлять описание

Следующий раздел нужен тем, кто поддерживает исходники или локальную копию портала.

Что правите	Где хранится исходный текст
Встроенную документацию нативного класса	XML в `Source/doc/classes/` либо `Source/modules/<module>/doc_classes/`. В нативном XML используются свои теги и ссылки, например `[method translate]` и `[param offset]`.
XML-комментарии управляемой реализации C#	Комментарии `///` в соответствующем C#-исходнике: `<summary>`, `<param name="...">`, `<returns>`, `<see cref="...">`. Это другой формат, чем BBCode нативного XML.
Проверенное RU/EN-описание на этом портале	`content/reference/overrides.json` в копии портала. Переопределение выбирается по точному XML ID объявления.
Руководство портала	Файлы `content/manual-edits/ru/` и `en/`, зарегистрированные в `content/manual-edits.json`.

Сигнатуры портала формируются из контракта SDK, а не из перевода текста. Правка описания не требует менять ядро движка. Не исправляйте проблему API выдуманной сигнатурой в сгенерированном JSON. Если SDK действительно обновилась, сначала сформируйте новый контракт установленной SDK через инструмент scripts/sdk-reference; он принимает каталог SDK API и путь выходного JSON.

Для описаний используются отдельные ключи:

Ключ	Назначение
XML ID типа, например `T:Reckfell.Rect2`	Введение; короткое описание задаётся полем `brief` с RU/EN.
Точный XML ID члена	Описание конкретного свойства, метода или перегрузки.
XML ID + `#param:<имя>`	Описание одного аргумента.
XML ID + `#returns`	Объяснение возвращаемого значения.

Пример действующей правки аргумента:

JSON
{
  "M:Reckfell.Rect2.Intersects(Reckfell.Rect2,System.Boolean)#param:includeBorders": {
    "ru": "false по умолчанию; true учитывает касание сторон и углов. Не меняет правила HasPoint().",
    "en": "Defaults to false; true includes side and corner contact. Does not change HasPoint() boundary rules."
  }
}

Берите XML ID из контракта SDK, не составляйте его по одному имени метода. Не переводите имена аргументов внутри ключей. В обеих локалях сохраняйте одинаковый исполняемый код; переводите пояснения вокруг него.

Опубликовать правку в локальном портале

Из корня копии портала, при настроенном Python, актуальном контракте .runtime/qa/sdk-contracts.json и установленной SDK:

python scripts/build_reference.py
python scripts/refine_manual.py
python scripts/validate_docs.py

Порядок важен: после генерации справочника восстанавливаются авторские руководства и нормализуются ссылки, затем выполняется проверка. Команда make rst не является процессом публикации этого портала. Не редактируйте content/docs/ как единственный источник правки: повторная генерация её затрёт.

Сохранённые импортированные описания отделены от сгенерированных страниц. Изменение нативного XML само по себе не переписывает уже сохранённые переводы и переопределения. Не запускайте --refresh-prose поверх готового C#-справочника: этот режим предназначен для захвата после свежего импорта исходных описаний.

Эти команды обновляют контент на диске. Поисковый сервис индексирует его при запуске; после проверки обновите работающий сервис документации способом, принятым в вашей установке. Проверьте обе локали, ссылку на нужную перегрузку и поиск по задаче. Статус технической проверки записывайте только после сверки с реализацией и необходимых проверок примера; явно фиксируйте, что осталось непроверенным.