Wie füge ich PHP-Codeblöcke in einen PHPDoc DocBlock ein

Question 1

Ich spiele mit PHPDoc herum und habe festgestellt, dass Sie Markdown verwenden können, um einem DocBlock einige Formatierungen hinzuzufügen. Insbesondere fällt mir auf, dass Sie Backticks verwenden können, um Inline-Code hervorzuheben.

Ich kann jedoch nicht herausfinden, wie Codeblöcke zu einem DocBlock hinzugefügt werden, da die Verwendung von 4 Leerzeichen nicht zu funktionieren scheint.

Ich habe versucht, mit <code> und <pre> auch, und obwohl diese Tags in der generierten Dokumentation erscheinen, wird der Code darin mit HTML-Kommentaren auskommentiert.

Zum Beispiel dieser DocBlock:

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

Erzeugt dieses HTML:

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

Wo gehe ich falsch? Wie kann ich meinem DocBlock einen Codeblock hinzufügen?

Question 2

phpdocumentor verwendet die Github-Variante von markdown.

Der richtige Weg, Code hinzuzufügen, ist dann:

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

Question 3

Das phpDocumentor-Handbuch sagt das für Beschreibungen

Sie können Ihren Text entsprechend formatieren Abschlaggenauer Markdown mit Github-Geschmack. Mit diesem Format ist es einfach, Ihren Text fett zu machen, Inline-Codebeispiele hinzuzufügen oder einfach Links zu anderen Websites zu generieren. — Innerhalb von DocBlocks

Das PSR-5 PHPDoc sagt für Beschreibungen

Jede Anwendung, die die Beschreibung parst, wird EMPFOHLEN, die Markdown-Auszeichnungssprache für dieses Feld zu unterstützen, damit der Autor eine Formatierung und eine klare Darstellung von Codebeispielen bereitstellen kann. — Beschreibung

Und das Stichworte

MUSS Markdown als Formatierungssprache unterstützen. Aufgrund der Natur von Markdown ist es zulässig, die Beschreibung des Tags in derselben oder der nachfolgenden Zeile zu beginnen und auf dieselbe Weise zu interpretieren. — Schild

Beispiel für PHPDoc mit Github-Flavoured 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)
{
    ...
}

Question 4

Ich denke nicht, dass Sie das hinzufügen sollten <?php -Tag, würde ich davon ausgehen, dass es beim Parsen entfernt wird. Da es sich um phpdoc handelt, können Sie es wahrscheinlich ganz überspringen.

Versuchen

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

Question 5

Sie sollten in der Lage sein, Folgendes zu verwenden: -

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