Как поместить блоки PHP-кода в PHPDoc DocBlock

Я играю с PHPDoc и понял, что вы можете использовать уценку, чтобы добавить некоторое форматирование в DocBlock. В частности, я замечаю, что вы можете использовать обратные тики, чтобы выделить встроенный код.

Однако я не могу понять, как добавить блоки кода в DocBlock, поскольку использование 4 пробелов не работает.

Я пробовал использовать <code> и <pre> тоже, и пока эти теги появляются в сгенерированной документации, код внутри них закомментируется комментариями HTML.

Например, этот DocBlock:

/**
 * This is a test DocBlock
 *
 * <pre>
 *     <?php
 *         echo('hi');
 *     ?>
 * </pre>
 *
 * @return object[] An array of objects.
 */

Создает этот HTML-код:

<pre>
    <!--?php echo('hi'); ?-->
</pre>

Где я ошибаюсь? Как добавить блок кода в свой DocBlock?

Ответ 1

phpdocumentor использует вариант github markdown.

Правильный способ добавления кода:

/**
 * This is a test DocBlock
 *
 * ```php
 * echo('hi');
 * ```
 *
 * @return ...
 */

Ответ 2

Я не думаю, что вы должны добавить тег <?php, я бы предположил, что он отключит его при разборе. Видя phpdoc, вы можете, вероятно, пропустить все это.

попробовать

 * <code>
 *         echo('hi');
 * </code>

Ответ 3

В руководстве phpDocumentor указано, что для Описания

вы можете отформатировать текст в соответствии с Markdown, а точнее Giddub-приправленный Markdown. Используя этот формат, легко сделать текст полужирным шрифтом, добавить примеры встроенных кодов или легко создать ссылки на другие сайты. — Inside DocBlocks

PSR-5 PHPDoc говорит для Описания

Любое приложение, анализирующее описание, РЕКОМЕНДУЕТСЯ для поддержки языка разметки Markdown для этого поля, чтобы автор мог обеспечить форматирование и четкий способ представления примеров кода. — Description

И что Теги

ДОЛЖЕН поддерживать Markdown как язык форматирования. Из-за характера Markdown законно начинать описание тега на той же или последующей строке и интерпретировать его таким же образом. — Tag

Пример PHPDoc с использованием Github-Flavored Markdown

/**
 * This is a Summary.
 *
 * This is a Description. It may span multiple lines
 * or contain 'code' examples using the _Markdown_ markup
 * language.
 *
 * It very easy to make some words **bold** and other 
 * words *italic* with Markdown. You can even 
 * [link to Google!](http://google.com).
 *
 * Here an example of how you can use syntax 
 * highlighting with GitHub Flavored Markdown:
 *
 * ```
 * <?php
 * echo "Hello, world.";
 * ?>
 * ```
 * 
 * You can also simply indent your code by four spaces:
 * 
 *     <?php
 *     echo "Hello, world.";
 *     ?>
 *
 * @see Markdown
 *
 * @param int        $parameter1 A parameter description.
 * @param \Exception $e          Another parameter description.
 *
 * @\Doctrine\Orm\Mapper\Entity()
 *
 * @return string
 */
function test($parameter1, $e)
{
    ...
}

Ответ 4

Вы должны иметь возможность использовать: -

/**
 * This is a test DocBlock
 *
 * <pre>
 *     &lt;?php
 *         echo('hi');
 *     ?&gt;
 * </pre>
 *
 * @return object[] An array of objects.
 */