CONTRIBUTING.md

Контрибьюторам: как внести свой вклад в документацию

Документация Bitrix Framework находится в открытом репозитории на GitHub. Если вы нашли ошибку или хотите дополнить статью, отправьте нам Pull Request.

Tip

Как отправить Pull Request

Чтобы все статьи выглядели единообразно, придерживайтесь правил оформления текста и примеров кода.

Текст статьи

Документация создается в формате Markdown. Для генерации сайта используется платформа Diplodoc. Платформа поддерживает синтаксис Yandex Flavored Markdown — расширенный вариант Markdown с дополнительными возможностями. Описание синтаксиса можно найти в официальной документации Diplodoc.

Схемы в статьях

Не используйте встроенные диаграммы, например Mermaid.

Используйте один из двух способов:

• изображение PNG — для скриншотов интерфейса и рисунков,

• текстовую схему в блоке кода с пометкой text — для структур объектов, порядка вызовов и связей между ними.

Файл изображения положите в папку _images рядом со статьей. В подписи опишите, что показано на картинке: ![Порядок обработки запроса](_images/request-flow.png).

Пример текстовой схемы:

запись Template ──> идентификатор исходного файла
                               │
                               v
                            Storage
                               │
                               v
                             Body
                               │ обработка полей
                               v
запись Document ──> идентификатор файла результата

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

Примеры кода

Для примеров PHP-кода в статьях следуйте стандарту PER Coding Style 3.0 (PHP-FIG). Помимо стандарта, в документации действуют дополнительные правила оформления кода.

Кавычки для строк

• Для простых строк используйте одинарные кавычки ''.

• Двойные кавычки "" используйте только при интерполяции или если экранирование мешает чтению.

// Простая строка — используем одинарные кавычки
$title = 'Report';

// Интерполяция переменной — допустимы двойные кавычки с фигурными скобками
$message = "Hello, {$name}";

// Строка с апострофом — двойные кавычки удобнее
$text = "User's guide";

Фигурные скобки в управляющих конструкциях

Всегда переносите открывающую фигурную скобку в управляющих конструкциях { на следующую строку. Закрывающую скобку } также ставьте на отдельной строке после тела конструкции.

if ($expr)
{
    doSomething();
}
else
{
    doOther();
}

for ($i = 0; $i < 10; $i++)
{
    echo $i;
}

Цепочки вызовов

Если цепочка вызовов не помещается в одну строку:

• перенесите первый вызов метода на новую строку,

• пишите каждый следующий вызов с новой строки,

• ставьте точку с запятой ; на новой строке на уровне первой строки.

// Цепочка вызовов для существующего объекта
$file
    ->setId($id)
    ->setContent($content)
    ->setName($name)
;

// Цепочка вызовов при присваивании
$superFile =
    $file
        ->setId($id)
        ->setContent($content)
        ->setName($name)
;