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

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

[!TIP]
Как отправить Pull Request

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

Текст статьиТекст статьи

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

Примеры кодаПримеры кода

Для примеров 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)
        ;