found - phpdoc example

¿Cómo coloco bloques de código PHP en un DocBlock PHPDoc?

Question

Estoy jugando con PHPDoc y me he dado cuenta de que puedes usar markdown para agregar algo de formato a un DocBlock. En particular, me doy cuenta de que puede usar marcas anteriores para resaltar el código en línea.

Sin embargo, no puedo encontrar la forma de agregar bloques de código a un DocBlock, ya que el uso de 4 espacios no parece funcionar.

También he intentado usar <code> y <pre> , y aunque esas etiquetas aparecen en la documentación generada, el código que contiene se comenta con comentarios HTML.

Por ejemplo, este DocBlock:

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

Genera este HTML:

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

¿A dónde me voy mal? ¿Cómo puedo agregar un bloque de código a mi DocBlock?

Answer 1

Deberías poder usar: -

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

Answer 2

El manual de phpDocumentor dice que para Descripciones

Puede formatear su texto de acuerdo con Markdown , más específicamente Markdown con sabor a Github . Usando este formato es fácil hacer que el texto esté en negrita, agregar ejemplos de código en línea o generar enlaces a otros sitios fácilmente. - Dentro de DocBlocks

El PSR-5 PHPDoc dice para descripciones

Cualquier aplicación que analice la Descripción se RECOMIENDA para que sea compatible con el lenguaje de marcado de Markdown para este campo, de modo que el autor pueda proporcionar formato y una forma clara de representar ejemplos de código. - Description

Y que las etiquetas

DEBE ser compatible con Markdown como lenguaje de formato. Debido a la naturaleza de Markdown, es legal comenzar la descripción de la etiqueta en la misma línea o en la línea subsiguiente e interpretarla de la misma manera. - Tag

Ejemplo de PHPDoc usando 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''s very easy to make some words **bold** and other 
 * words *italic* with Markdown. You can even 
 * [link to Google!](http://google.com).
 *
 * Here''s 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)
{
    ...
}

Answer 3

No creo que debas agregar la etiqueta <?php , asumiría que la eliminará en el análisis. Al ver como phpdoc, probablemente puedas omitirlo por completo.

tratar

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

Answer 4

phpdocumentor utiliza la variante github de markdown.

La forma correcta de agregar código, es entonces:

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