Как написать блок кода, используя phpDocumentor, учебники/расширенную документацию?

Как писать блоки кода с помощью phpDocumentor при написании учебников/расширенной документации?

Я пробовал <programlisting>, он может сгенерировать тэг <code>, но он не анализирует его содержимое.

<refentry id="{@id}">  

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

 <refsynopsisdiv>  
  <author>  
   My Name
   <authorblurb>  
    {@link [email protected] 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>

Ответы

Ответ 1

Это действительно очень просто, как только вы знаете, как это сделать. Вам просто нужно установить атрибут role в элементе programlisting.

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

Я не мог найти это документально нигде, кроме краткого упоминания в примечаниях к выпуску, но, глядя на код, кажется, что для поддержки четырех ролей:

  • php - добавляет подсветку синтаксиса PHP к содержимому и включает номер строки в каждой строке.
  • учебник - добавляет синтаксис синтаксиса HTML в контент и включает номер строки в каждой строке.
  • xml - добавляет теги pre к содержимому, но в противном случае нет синтаксиса hightlighting и нет номеров строк.
  • html - обрабатывает содержимое как необработанный HTML, поэтому вы можете использовать любую понравившуюся вам разметку.

В любое время, когда вы хотите использовать угловые скобки, вам нужно будет избежать этих символов или обернуть содержимое в разделе CDATA. Это даже применяется, если вы хотите использовать необработанный HTML. Если нет, синтаксический анализатор попытается интерпретировать содержимое как XML.

Например, образец необработанного HTML будет выглядеть примерно так:

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

Также обратите внимание, что все это относится к исходной версии phpDocumentor. Насколько мне известно, новая версия (phpDocumentor 2), по-видимому, не поддерживает учебники/расширенную документацию.

Ответ 2

Я проверил его, и я думаю, вы можете использовать инструмент документации javascriptMVC. я thik Инструмент документации.
и демо-версия здесь. и я предлагаю вам попробовать это. (-:

вот вывод документа javascriptMVC, который/я думаю, что вы хотите. или, по крайней мере, я надеюсь. (-: enter image description here

и о 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');
     <...>
 }

Ответ 3

Пользовательский инструмент zend studio может автоматически генерировать выбранную документацию проекта