PHPDocの書き方を学ぶ

Published: 2017年1月16日 by tomsato

概要

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

PHP

コメントを書く

※ Emailは公開されません

※ コメントは承認されると下記に表示されます

コメント一覧

最近の投稿

社内ツールなどの超小規模なAPIをGolangで実装する際にフレームワークを使うべきかを、実際にnet/httpを使った実装とフレームワークを使った実装を比較することでどれだけ優位性があるかを見ていきたいと思います。今回はフレームワークにはシンプルで使いやすそうなEchoを使うことにします。

vue-pdfを使ってNuxt.jsで作成しているアプリケーションに pdfスライドを表示させるサンプルを作成しました README.md通りに実装してもうまくいかないところがあったのでそのあたり含めてまとめます

Vue.js / Nuxt.jsにおけるログインの実装方法をまとめる Auth0やNuxt.jsのAuth Moduleとmiddlewareについて調べつつサンプルを作成することで理解を深める

コンポーネント設計について考える Atomic DesignやPresentational Component, Container Componentについてまとめつつ 自分だったらVue.js / Nuxt.jsでどういうコンポーネント設計にするかについてまとめます

Netlify Formsを使ってブログサイトにコメント機能を追加する方法を調べたので紹介 Netlify FormsはNetlifyに標準機能として用意されているフォーム機能 サーバレスなので別途コメント用にサーバを用意する必要がなくHTMLを埋め込むだけで準備できる

カテゴリ一覧

タグ一覧