Документация Docs/ru/contributing/documentation/snippets.md

Проверка фрагментов документации

Это руководство определяет проверяемый контракт для fenced-примеров в самодостаточной документации FOnline Engine. Проверенная политика хранится в BuildTools/SnippetPolicy.json, а текущие сгенерированные инвентарь и результат — в generated/snippets.json.

Состояние контракта

Каждый fenced block в публичном актуальном документе для людей из documentation-manifest.json входит в корпус фрагментов. Fence без указания языка или с неподдерживаемым языком считается ошибкой. Сгенерированные справочные страницы проходят ту же проверку, что и написанные вручную.

Языки кода, команд, конфигурации и данных являются нормативными. Каждый нормативный блок должен пройти объявленный parser harness. Обычные блоки text содержат свидетельства: ожидаемый вывод, журналы, деревья файлов, диаграммы или формы wire-данных. Они остаются в инвентаре и проходят структурную проверку, но не выдаются за исполняемый код.

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

Проверяющие механизмы

Язык	Harness	Проверяемая граница
`bash`	`bash-parse`	Статические проверки и настоящий parser Bash в режиме `bash -n`
`powershell`	`powershell-parse`	Статические проверки и языковой parser PowerShell
`cmake`	`cmake-parse`	Полные вызовы команд, комментарии, строки и сбалансированные аргументы
`cpp`, `csharp`, `angelscript`, `glsl`	`c-family-parse`	Строки, комментарии и сбалансированные круглые, квадратные и фигурные скобки
`ini`	`ini-parse`	Секции, присваивания, продолжения и структура встроенных vertex/fragment shader
`json`	`json-parse`	Строгий JSON parser Python
`python`	`python-parse`	Parser AST Python
`text`	`text-contract`	Непустой UTF-8 текст без запрещённых управляющих символов
`xml`	`xml-parse`	Разбор одного полного XML-документа через Python `ElementTree`

Команды Bash и PowerShell только разбираются и никогда не выполняются. Перед разбором документированные placeholders в угловых скобках и многоточия заменяются инертными токенами. Эта замена нужна только parser; сгенерированный отчёт сохраняет template: true, чтобы грамматический шаблон нельзя было принять за проверенную конкретную команду.

C-family harness доказывает лексическую структуру, а не корректность типов C++, C# или AngelScript. Если фрагмент обещает компиляцию, baking, запуск или runtime- результат, ему всё ещё нужен названный в руководстве владеющий тест исходника или примера. Snippet gate не пропускает испорченную документацию, но не превращает изолированный фрагмент в семантическое доказательство сборки.

Запуск проверки

Из корня Engine запустите python BuildTools/docs_snippets.py --write --external после изменения fenced-содержимого или политики. Для фокусных regression-тестов запустите python BuildTools/tests/test_docs_snippets.py, а для точной CI-проверки — python BuildTools/docs_snippets.py --check --external.

--write обновляет только детерминированный отчёт. --check отклоняет отсутствующий или устаревший результат. --external требует оба настоящих shell parser; используйте DOCS_BASH или DOCS_POWERSHELL только для выбора установленного исполняемого parser и никогда не подменяйте harness оболочкой, которая выполняет команды.

Основная задача документации запускает фокусные тесты и статическую проверку актуальности. Отдельная задача documentation-snippets запускает внешние parser без нативной сборки Engine. Так быстрая проверка исходников остаётся переносимой, а production-свидетельство настоящих parser становится обязательным в CI.

Создание или изменение фрагмента

Поместите пример во владеющий публичный документ и укажите один поддерживаемый язык в открывающем fence.
Предпочитайте полную команду или пример, подтверждённый исходником. Используйте placeholders только для настоящих параметров грамматики или справочника, а не чтобы пропустить основные шаги руководства.
Держите ожидаемый вывод в отдельном блоке text. Не помечайте вывод как shell- или source-язык только ради внешне более сильного результата.
Перегенерируйте отчёт фрагментов и проверьте в записи идентификатор документа, заголовок, harness, признак шаблона и состояние.
Запустите семантического владельца: скомпилируйте примеры C++/AngelScript, сконфигурируйте CMake, выполните baking авторских данных или узкий smoke- сценарий примера, если текст обещает такие результаты.
После отчёта фрагментов перегенерируйте локализацию, site/search, AI evaluation и AI delivery, поскольку эти артефакты хэшируют или зеркалируют изменённый корпус документации.

Перемещение fence меняет записанную строку исходника. Изменение содержимого меняет нормализованный хэш и сгенерированный ID. Оба сигнала актуальности намеренны; никогда не редактируйте отчёт вручную ради сохранения устаревшей идентичности.

Шаблоны и ожидаемый вывод

Отчёт помечает блок как шаблон, если в command/CMake/text-блоке есть placeholder в угловых скобках либо ASCII/Unicode-многоточие. Шаблон может оставаться нормативным и parser-valid, но не доказывает выполнимость задачи. Руководства и release-процедуры должны разрешать шаблоны до точных путей, целей, ревизий и сигналов успеха через пример, принадлежащий Engine, либо помеченный тегом публичный репозиторий.

Свидетельство text проверяется только на транспортную безопасность. Если текст обещает точный вывод, источником доказательства остаётся владеющий smoke/unit/integration-тест; при изменении вывода его нужно обновить в том же изменении.

Обработка ошибок

Не указан язык: выберите фактический синтаксис; используйте text только для вывода или диаграмм.
Неизвестный язык: прежде чем использовать язык, добавьте проверенный harness и запись политики.
Ошибка статического parser: исправьте пример или явно пометьте настоящие параметры грамматики; не ослабляйте проверки разделителей и секций.
Ошибка внешнего shell parser: воспроизведите её с указанным блоком и parser в режиме без выполнения, затем исправьте shell-синтаксис или форму placeholder.
Устаревший отчёт: перегенерируйте его после всех изменений исходника и затем проверьте diff.
Семантическая сборка падает при зелёном snippet gate: исправьте пример и владеющий compile/bake/smoke-тест. Лексическая корректность не является семантическим доказательством.

Не добавляйте список исключений для неудобных примеров. Если fenced block не содержит код или свидетельство, которое стоит поддерживать, удалите fence или устаревшее содержимое.