PHPを使ってプログラムを書いていてJavadocのようなドキュメントを作成できたらいいなぁと思ってPhpDocumentorを使ってみました。

まずは、WindowsにXAMPPをインストールした環境でのPhpDocumentorのセットアップの方法です。

PhpDocumentorのセットアップ

1.  XAMPPのPHPインストール先のフォルダにPATHを設定します。
   （XAMPPのセットアップについてはこちらをご覧ください）
   ◆PATHの設定方法◆
   ■  Windows2000、XPでの設定方法
   「コントロールパネル」から「システム」を開きます。
   すると、「システムのプロパティ」ウインドウが開くので「詳細」タブを選択し「環境変数」ボタンを押下します。
   
   環境変数の設定ウインドウが開きます。
   「システム環境変数」の中に「PATH」という変数があるので選択し、編集ボタンを押下します。
   
   「PATH」の編集画面が表示されるので、「C:\xampp\php;」を追加します。
   追加したら「OK」ボタンを押下します。
   ※「;」がPATHの区切り文字になっているので前のパスとの間に「;」があることを確認してください。
   

    ■ WindowsVistaでの設定方法
     「コントロールパネル」から「システムとメンテナンス」を開きます。
   
   すると、「システムとメンテナンス」ウインドウが開くので「システム」を開きます。
   
   すると「システム」ウインドウが開くので、「システムの詳細設定」をクリックします。
   
   「システムのプロパティ」が開くので「詳細設定」のタブにある「環境変数」ボタンを押下します。
   
   環境変数の設定ウインドウが開きます。
   「システム環境変数」の中に「PATH」という変数があるので選択し、編集ボタンを押下します。
   
   「PATH」の編集画面が表示されるので、「C:\xampp\php;」を追加します。
   追加したら「OK」ボタンを押下します。
   ※「;」がPATHの区切り文字になっているので前のパスとの間に「;」があることを確認してください。
   

2. コマンドプロンプトを開いて、一度PhpDcumentorをアンインストール為に以下のコマンドを実行します。
   （XAMPPでインストールしていると既にインストールされていると思いますが一度アンインストールしください）

   1	pear uninstall phpdocumentor

3.  PhpDocumentorをインストールします。
   コマンドプロンプトで以下のコマンドを実行します。

   1	pear install -a phpdocumentor

   これで、PhpDocumentorのインストールが終了しました。

PhpDocumentorを使ってみよう

 コマンドを実行して、ドキュメントを作ってみましょう

例）

1

phpdoc -t ./phpdoc/ -d C:/htdocs/codeigniter/system/application/

-tオプションで出力先を決定、-dオプションでphpdocを処理するソースが存在するディレクトリを指定しています。

詳しいコマンドのオプション内容は、こちらをご覧ください。PDFファイルなどにも出力できますよ

 ちょっとだけコマンド解説

• -tオプション：作成されたファイルの出力先（相対パス、絶対パスどちらで指定することも可能です）
• -dオプション：ドキュメントを作成するファイルが入っているディレクトリを指定する（相対パス、絶対パスどちらで指定することも可能です）
• -fオプション：ドキュメントを作成するファイルを指定する（相対パス、絶対パスどちらで指定することも可能です）
• -oオプション：ドキュメントのレイアウトを指定する
  PDFや、色々なHTMLのレイアウトが指定できます。
  例）PDFでの出力

  1	phpdoc -t ./phpdoc -d ./application -o PDF:default:default

  例）デフォルトとは違うレイアウトでの出力（日本語も文字化けしないのでこれはお勧めの設定）

  1	phpdoc -t ./phpdoc -d ./application -o HTML:Smarty:PHP

  他にも先ほどphpdocのコマンドのリファレンスの-oオプションの場所に色々なoutputの出力できる定義がのっているので試してみてください。
  （中には文字コードが指定されている為に、日本語が文字化けするものも存在するので注意が必要です）

出力種類の一覧） -oオプションで使用できる値は以下のものになります

ドキュメントが英語で書かれているので面倒なので-oオプションで使用できる値の一覧を抜粋して書いておきました

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

HTML:frames:* - output is HTML with frames.
      HTML:frames:default - JavaDoc-like template, very plain, minimal formatting
      HTML:frames:earthli - BEAUTIFUL template written by Marco von Ballmoos
      HTML:frames:l0l33t - Stylish template
      HTML:frames:phpdoc.de - Similar to phpdoc.de PHPDoc output
      HTML:frames:phphtmllib - Very nice user-contributed template
      HTML:frames:phpedit - Based on output from PHPEdit Help Generator
 
HTML:Smarty:* - output is HTML with no frames.
      HTML:Smarty:default - Bold template design using css to control layout
      HTML:Smarty:HandS - Layout is based on PHP, but more refined, with logo image
      HTML:Smarty:PHP - Layout is identical to the PHP website
 
CHM:default:* - output is CHM, compiled help file format (Windows help).
      CHM:default:default - Windows help file, based on HTML:frames:l0l33t
 
PDF:default:* - output is PDF, Adobe Acrobat format
      PDF:default:default - standard, plain PDF formatting
 
XML:DocBook:* - output is XML, in DocBook format
      XML:DocBook/peardoc2:default - documentation ready for compiling into peardoc for online pear.php.net documentation, 2nd revision

PhpDocument用のコメントの書き方

コメントの書き方は、こちらを見てください。