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

【问题标题】：How to write code block using phpDocumentor, tutorials/extended documentation?如何使用 phpDocumentor、教程/扩展文档编写代码块？
【发布时间】：2013-04-16 09:05:18
【问题描述】：

如何在编写教程/扩展文档的同时使用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>

【问题讨论】：

你会在你的问题中编辑一个你尝试过的例子吗？您的意思是在函数/方法之前的注释块内？
不，这不是关于函数之前的注释块，而是关于编写教程/扩展文档。这是不同的。

标签： php external phpdoc

【解决方案1】：

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

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

除了release notes 中的简短提及外，我在任何地方都找不到此文档，但从查看代码来看，似乎支持四个角色：

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

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

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

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

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

【讨论】：

Tnx，这正是我一直要求的。

【解决方案2】：

我检查了它，我认为您可以使用 javascriptMVC 文档工具。我认为Documentation Tool.
以及它的演示is here。我建议你试试这个。(-:

这里是 javascriptMVC 的 documentJs 的输出，它是 /i 认为你想要的东西。或者至少我希望。（-：

关于 phpDocumentor 正如我所说，我需要一些解释来理解你的意思，但现在请检查这些。 link1。 link2 。（如果以下是您想要的）。

 /** @type int This is a counter. */
 $int = 0;

 // there should be no docblock here
 $int++;

或者：

 /**
  * This class acts as an example on where to position a DocBlock.
  */
 class Foo
 {
     /** @type string|null Should contain a description if available */
     protected $description = null;

     /**
      * This method sets a description.
      *
      * @param string $description A text with a maximum of 80 characters.
      *
      * @return void
      */
     public function setDescription($description)
     {
         // there should be no docblock here
         $this->description = $description;
     }
 }

另一个例子是在 foreach 中显式地记录变量；许多 IDE 使用这些信息来帮助您自动完成：

 /** @type \Sqlite3 $sqlite */
 foreach($connections as $sqlite) {
     // there should be no docblock here
     $sqlite->open('/my/database/path');
     <...>
 }

【讨论】：

我不需要javascript文档，标题是phpDocumentator。
@Antagonist 好的，给我一些时间。
@Antagonist 好的，你能解释一下你的意思而不是“解析它的内容”吗？
伙计，我非常感谢您为帮助我所做的努力，但我认为您的方向错了。我知道如何编写标准注释块。我不知道如何编写代码示例（ cmets 包含代码）在编写 EXTENDED DOCUMENTATION 时。所以你应该首先关注 EXTENDED DOCUMENTATION 也称为 TUTORIALS 的含义。以及 PARSE ITS CONTENTS 的含义：PhpDocumentator 应该能够“理解” cmets（识别 PHP 语言），并以不同的颜色显示代码。例如：单词“class”应为蓝色。
这里有一个链接manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/… 看看我在说什么

【解决方案3】：

您可以使用zend studio工具，它可以自动生成选定的项目文档

【讨论】：