]> phpDocumentorでドキュメントの自動生成

phpDocumentorでドキュメントの自動生成

javaにはjavadocと言う、ソースファイルからjavaのリファレンスマニュアルを生成してくれるコマンドがありますが、phpにも同様のものとしてphpDocumentorがあります。これはPEARパッケージの１つとして提供されていて、PEARを導入していれば簡単にインストールが可能です。

phpDocumentorの特徴としては、ドキュメントのoutput形式として、下記のようなフォーマットがサポートされています。

  1. html(複数のテンプレートから選択が可能)
  2. PDF
  3. Windows Help

phpDocumentorのインストール

インストールはpearコマンドで簡単にインストール出来ますが、memory_limitがデフォルト値(8M)のままだとメモリー不足でインストール出来ませんでした、php.iniを修正してmemory_limitを16Mに増やせば問題なくインストール出来きました。

;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;
  
max_execution_time = 30     ; Maximum execution time of each script, in seconds
max_input_time = 60     ; Maximum amount of time each script may spend parsing request data
memory_limit = 16M      ; Maximum amount of memory a script may consume (8MB)

インストールは次のように行います。

# pear install --alldeps phpdocumentor
downloading PhpDocumentor-1.2.3.tgz ...
Starting to download PhpDocumentor-1.2.3.tgz (2,656,621 bytes)
...................(略).......................done: 2,656,621 bytes
install ok: PhpDocumentor 1.2.3

インストールが正常に完了したならば、phpdocコマンドが使用可能になります。

# phpdoc --help
Parsing configuration file phpDocumentor.ini...
done
using default (slower) Parser - get PHP 4.3.0+
and load the tokenizer extension for faster parsing (your version is 4.3.10

  -f    --filename                name of file(s) to parse ',' file1,file2. 
                                  Can contain complete path and * ? wildcards
                      (以下略)

phpDocumentorの実行

phpDocumentorには沢山のオプションがあります。しかし、実際に使用するのは数種類だと思います。一番簡単にドキュメントを作成した場合は、下記のコマンドで十分でしょう。

# phpdoc -t ./doc  -d ./src -o HTML:Smarty:PHP

これを実行すると、src以下のphpファイルを解析して、doc以下にドキュメントを出力します。
-oオプションでドキュメントテンプレートを指定出来ます。HTMLに関してのドキュメント テンプレート オプションは次のものがあります。

HTML:frames:* - output is HTML with frames.

HTML:Smarty:* - output is HTML with no frames.

HTMLの文字化け

phpDocumentorで出力されたHTMLドキュメントですが、日本語が混ざっていると文字化けしてしまいます。これはHTMLヘッダのcharsetがiso-8859-1に固定で出力される為です。

phpDocumentorではテンプレートエンジンとしてSmartyを使用しているのですが、Smartyのテンプレートが納められているディレクトリ([pear install directory]/data/PhpDocumentor/phpDocumentor/Converters/HTML/)以下にあるheader.tplファイルのISO-8859-1と書かれている所をEUC-JPまたはShift_JISに変更すれば直ると思います。

header.tplの修正例

<?xml version="1.0" encoding="EUC-JP"?>  <!-- EUC-JPに変更 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml">
                <head>
                        <!-- template designed by Marco Von Ballmoos -->
                        <title>{$title}</title>
                        <link rel="stylesheet" href="{$subdir}media/stylesheet.css" />
                        <meta http-equiv='Content-Type' content='text/html; charset=EUC-JP'/>  <!-- EUC-JPに変更 -->
                </head>
                <body>
                        {if $top3}<div class="page-body">{/if}

ドキュメント化対象のファイル拡張子を増やす

ドキュメント化対象のファイル拡張子は、[pear install directory]/data/PhpDocumentor/phpDocumentor.iniに定義されています。

[_phpDocumentor_phpfile_exts]
php
php3
php4
phtml
inc

ここに、対象にしたい拡張子を追加すれば、その拡張子を持ったファイルはドキュメント化対象となります。

phpDocumentorの書き方

phpDocumentorの書き方の詳しい説明はphpDocumentor Manualに詳しく書かれていますが、基本的なものを説明します。

DocBlockの定義

phpDocumentorにはDocBlockと言う概念があって、ドキュメント化する際には、このDocBlockに書かれたものを文書化するようです。DocBlockは次のように定義します。

/**
 * 関数fooの説明文
   この行は先頭に"*"が無いので無視される
 */
function foo()
{

DocBlockは、/** から始まり、全てのコメント行の初めに"*"を持っている拡張C++スタイルのPHPコメントです。*で始まらないコメント行は無視されます。

関数fooのドキュメントであるDocBlockは、定義の直前に置かなくてはいけません。次の例では、define文のドキュメントになってしまいます。

/**
 * 関数fooの説明文
 */
define('me',2);
function foo()
{

DocBlocks

DocBlockは３つのセグメントから構成されています。

  1. Short Description(短い説明文)
  2. Long Description(長い説明文)
  3. Tags(タグ)

DocBlockの例

/**
 * Short Description
 *
 * Long description
 * 長い説明文は３行以上に渡って書くことが
 * 出来ます。
 * 空白行を入れると、そこはパラグラフの終りになります。
 *
 * ここは、第２パラグラフの始まりになります。
 *
 * @version  tagの例 version 1.0
 * @see タグの説明を参照してください。
 *
 */

Short DescriptionとLong Description

Short Descriptionは

  1. DocBlockの最初のラインから始まり、空白行またはピリオドで終わります。
  2. ピリオドが含まれる単語(example.com や 0.1%のような)の後ろは無視されます。
  3. ３行以上になる場合は、最初の１行だけが有効になります。
  4. HTML タグを含ませる事もできます。(記述可能なタグ)

Long Descriptionは

  1. 「長い説明文」は複数の行を書くことが出来ます。
  2. HTML タグを含ませる事もできます。(記述可能なタグ)

タグ

phpDocumentorのタグは、

  1. JavaDocのタグと非常に似通っています
  2. タグ行は改行文字までが有効になります(複数行には書けない)。
  3. タグ行の中にタグが存在するとそれは無視されます。

次の例は、@authorタグの中に@versionタグが存在するので、"@version tag is ignored"は無視されます。

/**
 * @author this tag is parsed, but this @version tag is ignored
 * @version 1.0 this version tag is parsed
 */

タグの中には、インラインタグが幾つか存在し、インラインタグはDescription中に書くことが出来ます。下記の例では、{@link foo()}は、ドキュメント上の関数foo()へのリンクとして生成されます。

/**
 * inline tags demonstration
 *
 * this function works heavily with {@link foo()} to rule the world
 */
  function bar(){ ... }
  function foo(){ ... }

DocBlockの種類

DocBlockは幾つかのエレメント毎にDocBlockを構成することが出来るようです。
構成出来るエレメントとしてglobal variable, include, constant, function, define, class, variable, method ,pageがあるようです。

どの様な構成になっているか以下に示します。

<?php
/**
 * Page-level DocBlock
 */
	    
/**
 * inlcude DocBlock
 */
require_once("inc.php");

/**
 * global variable DocBlock
 */
$GLOBALS['baz'] = array('foo','bar');

/**
 * define DocBlock
 */
define('THREE', 1+2);

/**
 * function DocBlock。
 */
function mine($arg1) { ... }

/**
 * class DocBlock
 */
class foo{
    /**
     * variable DocBlock
     */
    var who;

    /**
     * method DocBlock
     */
    function bar(){ }
}
?>

これに従ってサンプルを書いてみました。サンプルをphpDocumentorでドキュメント化すると次のようになります。

  1. o オプションにHTML:frames:earthliを指定した場合
  2. o オプションにHTML:Smarty:HandSを指定した場合

Standard phpDocumentor Tags

タグの中で使用頻度が高いタグの説明をしておきます。

@access

ドキュメントの出力制御を行うタグです。@accessは次の値を取ります。

  1. private：phpDocumentorのドキュメントとして出力されません。
  2. public：phpDocumentorのドキュメントとして出力されます。
  3. protected：良くわかりません。
/**
 * function func1, 省略時はpublicになります。
 */
function func1(){ ... }
/**
 * function func2, access は privateなので、この関数のドキュメントは出力されません。
 * @access private
 */
function func2(){ ... }

class class1
{
   /**
    * これは文書化される
    * @access public
    */
   function publicmethod(){ ... }
}

@author

作者を記述するタグ。
global variable, include, constant, function, define, class, variable, method ,pageで使用可能。
< >で括られた場所はメールアドレスとして解釈されます。

/**
 * @author Joe Shmoe <foo@bar.org>
 */

@copyright

copyrightの定義を行う
global variable, include, constant, function, define, class, variable, method, pageで使用可能。

/**
 * @copyright Copyright © 2002, Gregory Beaver
 */

@deprecated

ファイルやクラスが、もはや使われなくなっているが、 互換性のため残されている場合にこのタグを使用します。
global variable, include, constant, function, define, class, variable, method, pageで使用可能。

/**
 * @deprecated Method deprecated in Release 2.0.0
 */

@example

サンプルファイルなどをリンクさせたい場合使用する(だと思う)。リンクされたファイルはハイライトで表示される。

/**
 * @example ./sample.php 関数使用例
 */

@ignore

複数の定義がある場合、一方の定義を無視させる。

if ($ostest){
 /**
   * 同じ定義二つ存在する。 'Unix' or 'Windows'
   */
   define("OS","Unix");
} else {
 /**
   * こちらは無視させる。
   * @ignore
   */
   define("OS","Windows");
}

@link

linkを生成する。

  1. @link URL link text
  2. @link URL, URL, URL...
/**
 * Displays http://www.example.com
 * @link http://www.example.com
 */
define("TEST_CONSTANT",3);
/**
 * Displays Hello
 * @link http://www.example.com Hello
 */
define("TEST_CONSTANT2",3);

@param と @return

@paramは関数の引数について記述します。@returnは関数の戻値について記述します。

/**
 * example of basic @param usage
 * @param bool $baz 
 * @return mixed 
 */
function function1($baz)
{
   if ($baz)
   {
      $a = 5;
   } else
   {
      $a = array(1,4);
   }
   return $a;
}
/**
 * @param string $s 表示させる文字
 * @param mixed $v 値を表示させるvar_dump()から取得した値
 * @param mixed $v,... var_dump()から取得した値は可変長の引数リストになる
 */
function fancy_debug($s,$v)
{
   print $s."<blockquote>\n";
   var_dump($v);
   if (func_num_args()>2)
   {
      for($i=2;$i<func_num_args();$i++)
      {
         $a = func_get_arg($i);
         var_dump($a);
         print "<br>\n";
      }
   }
   print "</blockquote>\n";
}

@see

参照先を生成する。参照先が存在する場合はリンクが生成されます。

/**
 * @see b_func
 */
function a_func{ }
/**
 * @see a_fun
 */
function b_func{ }

@since

ファイルやクラスが、パッケージの初リリースの後で加えられた場合、このタグを使用します。

/**
 * Page-level DocBlock
 * @package BigImportantProjectWithLotsofVersions
 * @version 72.5
 */
/**
 * function datafunction
 * @since Version 21.1
 */
function datafunction()
{

@version

ページレベルブロックを含む任意の要素のバージョンを記述します。

inline {@link}

説明文中に、リンクを生成します。

/**
  * 説明文の{@link http://www.example.com ここがリンクになる} また {@link element} のようにも出来る
  */
Last modified: Mon Dec 17 22:30:22 2007 JST