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

Estoy jugando con PHPDoc y me di cuenta de que puedes usar Markdown para agregar algo de formato a un DocBlock. En particular, observo que puede usar marcas de retroceso para resaltar el código en línea.

Sin embargo, parece que no puedo descifrar cómo agregar bloques de código a un DocBlock, ya que usar 4 espacios no parece funcionar.

He intentado usar <code> y <pre> también, y aunque esas etiquetas aparecen en la documentación generada, el código dentro de ellas 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>

¿Dónde me estoy equivocando? ¿Cómo puedo agregar un bloque de código a mi DocBlock?

preguntado el 31 de julio de 12 a las 14:07

¿Has probado usar &lt; y &gt; en lugar de < y >? -

Hay documentación dice que ese es el uso correcto manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/… -

@MikeB Es interesante que el enlace sugiera que debería funcionar... es un poco incómodo usar &lt; y &gt; todo el tiempo... ¿Seguramente PHPDoc podría/debería convertirlos por mí? -

@MarkLocker Odd: también estoy viendo lo que estás viendo. Estoy usando PHPDocumentor 2.0.0a3 -

En mi propio uso, iría con Kasia y no usaría las etiquetas de apertura/cierre de PHP, ya que el contexto de los blocks should be clear enough. Mez's way of having the text equivalent of the tags should also work, avoiding any parser confusion by using the literal tag characters. Something I have not tried would be using double signs (< >) to see if they work, analogous to how "< >" can be used to print a literal " " ( blocks should be clear enough. Mez's way of having the text equivalent of the tags should also work, avoiding any parser confusion by using the literal tag characters. Something I have not tried would be using double signs (< >) to see if they work, analogous to how "< >" can be used to print a literal " " ( blocks should be clear enough. Mez's way of having the text equivalent of the tags should also work, avoiding any parser confusion by using the literal tag characters. Something I have not tried would be using double signs (< >) to see if they work, analogous to how "< >" can be used to print a literal " " (manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/…) -

4 Respuestas

phpdocumentor usa la variante github de markdown.

La forma correcta de agregar código es entonces:

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

Respondido el 11 de junio de 15 a las 10:06

El manual de phpDocumentor dice que para Descripción

puede formatear su texto de acuerdo con Reducción, más específicamente Markdown con sabor a Github. Con este formato, es fácil poner el texto en negrita, agregar ejemplos de código en línea o generar fácilmente enlaces a otros sitios. — Dentro de DocBlocks

La opción PSR-5 PHPDoc dice por Descripción

Se RECOMIENDA que cualquier aplicación que analice la descripción admita el lenguaje de marcado Markdown para este campo, de modo que el autor pueda proporcionar formato y una forma clara de representar ejemplos de código. — Descripción

Y eso Etiquetas

DEBE admitir 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 siguiente e interpretarla de la misma manera. — Etiqueta

Ejemplo de PHPDoc usando Markdown con sabor a Github

/**
 * 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)
{
    ...
}

Respondido 14 Oct 16, 08:10

No es que el OP haya preguntado por Eclipse, pero notaré que Eclipse-PDT Neon no parece respetar la reducción. Es una pena, ya que Markdown es más legible en línea que un montón de etiquetas HTML. - señal de desmayo

Muy bueno que esta respuesta cite la documentación y varios ejemplos de la sintaxis. Espero que esta respuesta obtenga suficientes votos para convertirse en la mejor respuesta. Estaba buscando una confirmación como esta en junio de 2016. - Sr. Lance E Sloan

Valora los ejemplos. No me di cuenta de que la sangría de 4 espacios era despues de un espacio siguiendo el asterisco. - Tim Morton

No creo que debas agregar el <?php etiqueta, supongo que se quitará al analizar. Al ver como phpdoc, probablemente pueda omitirlo por completo.

tratan

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

Respondido 31 Jul 12, 14:07

Deberías poder usar: -

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

Respondido 31 Jul 12, 14:07

@JunaidAtari Nop, porque es - El onin

No es la respuesta que estás buscando? Examinar otras preguntas etiquetadas or haz tu propia pregunta.