PHPDocの書き方を学ぶ


■ 目次

  1. 概要
  2. PHPDocの書き方
  3. PHPDocを記述する例
  4. ドキュメントを自動生成する

■ 概要

phpDocumentorとはクラスやメソッドの定義前にブロックコメントを決められた方式で記述していると、APIドキュメントを自動生成することができるツール

今回はそのphpDocumentorで記述する書式についてまとめる

■ PHPDocの書き方

前提知識

DocCommentの開始は以下のように記述する
※ 開始行のアスタリスクは必ず2つ

/**
  * @var int
  */
$num = rand(0, 10);

1行で記述することもできる

/** @var int */
$num = rand(0, 10);

「//」を使ったコメントではDocCommentにはならにことに注意

■ PHPDocを記述する例

ファイルの先頭

目的など簡潔に記述する

<?php
/**
 * このファイルではPHPDocの説明をします
 *
 * @copyright 会社名 All Rights Reserved
 * @license https://opensource.org/licenses/mit-license.html MIT License
 * @author 名前 <メールアドレス>
 * @link 資料
 */

クラス

/**
 * このクラスではXXXを行います
 *
 * 1行空けてもう少し詳しく記述することができる
 * 複数行記述ができて、不要なら省略もできる
 *
 * @access アクセスレベル
 * @author 名前 <メールアドレス>
 * @copyright 会社名 All Rights Reserved
 * @category カテゴリー(処理系)
 * @package パッケージ(MVC)
 */

メソッド

@paramで関数の引数を記述できる
@returnで関数が返す型を記述できる(int,float,void,arrayなど)
returnが複数の型を返す場合はstring|booleanなどと記述する

/**
 * このメソッドはXXを行います
 *
 * 詳細(略)
 *
 * @access アクセスレベル
 * @param int    $id
 * @param string $name
 * @return boolean ユーザが存在するかどうか
 * @link 参考資料のURL
 * @see 関連(呼び出したり)する関数
 * @throws 可能性のある例外を記述する
 * @todo TODO事項
 */
function isExistsUser($id, $name)
{ 関数の中身は省略 }

変数

@varタグは変数の型を明示できるが
メソッドの戻り値の型が不明な場合にのみ記述する方が良い

/** @var string 名前 */
$name;

■ ドキュメントを自動生成する

実際に作成してみる

// composerで導入するのでcomposerを準備
$ sudo bash -c "curl -sS https://getcomposer.org/installer | php"
$ sudo mv composer.phar /usr/local/bin/composer
// phpdocumentor導入
$ composer require "phpdocumentor/phpdocumentor:2.*"

既にPHPDoc形式でコメントを記述したPHPファイルがあるとしてphpdocコマンドでHTMLを作成する

$ ./vendor/bin/phpdoc -t output/ -d src/
 -t: DOCの出力先
 -d:DOCにする対象フォルダ
 -o:出力形式の指定

出力されたHTML群を表示させると以下のようにドキュメントが作られている

phpdoc01


Be First to Comment

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です