新しいブログに移動しました。
9ensanのLifeHack
こちらの記事も必要に応じて新しいブログに移動させる予定です。
今後ともよろしくお願い致します。

HOME > 

phpdocumentor

PHPのドキュメント作成にPhpDocumentorを使ってみる コメントの書き方

  • 2009.03.01 (日) 10:29
  • PHP

PhpDocumentorを使用する場合のコメントの書き方についてのまとめです。

PhpDocumentorの使い方については以前に書いた記事があるのでこちらを見てください。

自分が書くときの備忘録なので、詳しい内容が知りたい方はPhpDocumentorのドキュメントを見てください。

クラスを記述する時のコメント

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * DB管理ツールクラス
 *
 * 以下の機能を保持しているクラス
 * テーブルの作成、データの登録、更新、削除、検索ができる。
 * データのインポート、エクスポート機能
 *
 * @access public
 * @author Masaru Hashizume
 * @copyright Copyright (c) 2009, Masaru Hashizume
 * @version 1.00
 * @since 2009/02/21
 */

プロパティ/変数に記述する時のコメント

1
2
3

/**
* PDO
*/

関数/メソッドに記述する時のコメント

1
2
3
4
5
6
7
8
/**
 *
 * NewEntryテーブルにデータを登録する
 *
 * @access public
 * @param  array 登録データ
 * @return void
 */

コメントに使用する記述内容一覧

1
2
3
4
5
6
7
8
9
10
@abstract
@final
@access public
@author Masaru Hashizume
@copyright Copyright (c) 2002, Masaru Hashizume
@param bool $baz
@return mixed
@version 1.00
@see function parent_method
@since 2009/03/01

PHPのドキュメント作成にPhpDocumentorを使ってみる

  • 2009.02.22 (日) 09:31
  • PHP
  • ,

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

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

PhpDocumentorのセットアップ

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

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

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

お薦めのレンタルサーバー
広告
お薦めの書籍
HOME > 

phpdocumentor