php - 如何使用 phpDocumentor、教程/扩展文档编写代码块？

Question

如何在编写教程/扩展文档时使用 phpDocumentor 编写代码块？

我试过了<programlisting> , 它可以生成 <code>标记，但它不解析其内容。

<refentry id="{@id}">  

 <refnamediv>  
  <refname>Guide for MyApp</refname>  
  <refpurpose>To demonstrate ...</refpurpose>  
 </refnamediv>  

 <refsynopsisdiv>  
  <author>  
   My Name
   <authorblurb>  
    {@link mail@mail.com My Name}  
   </authorblurb>  
  </author>  
 </refsynopsisdiv>  

 {@toc}  
 <refsect1 id="{@id intro}">  
  <title>User Guide for MyApp</title>  

  <para>  
   Some Description
  </para>

      <programlisting>

            $some = 'code';

      </programlisting>

 </refsect1>
</refentry>

Answer 1

一旦您知道如何操作，这实际上非常容易。您只需在 programlisting 元素上设置 role 属性。

<programlisting role="php">
  $some = 'code';
</programlisting>

除了在 release notes 中的简短提及外，我无法在任何地方找到此文档。 ，但是从代码来看，似乎支持四种角色:

1. php - 为内容添加 PHP 语法高亮显示，并在每一行包含一个行号。
2. 教程 - 向内容添加 HTML 语法高亮显示，并在每一行中包含一个行号。
3. xml - 在内容周围添加 pre 标记，但除此之外没有语法高亮显示和行号。
4. html - 将内容视为原始 HTML，因此您可以使用任何您喜欢的标记。

不过，任何时候您想要使用尖括号时，您都需要转义这些字符或将内容包装在 CDATA 部分中。这甚至适用于您想要使用原始 HTML 的情况。否则，解析器将尝试将内容解释为 XML。

例如，原始 HTML 示例看起来像这样:

<programlisting role="html">
  <![CDATA[
    <b>This sentence will be bold.</b>
  ]]>
</programlisting>

另请注意，所有这些都适用于 phpDocumentor 的初始版本。据我所知，新版本 (phpDocumentor 2) 似乎不支持教程/扩展文档。