【PHP】コメントマスターになろう！

2019年8月11日 2019年10月17日

たかぽん

どーも！

今回は動作にはあまり関係しないのですが、チームで開発するなら必ず心得てほしいコメントについて簡単に説明していきます！

多人数で開発するなら特に知っておいたほうがいい内容ですっ！

1 コメントとは？
2 Docコメントとは？
- 2.1 Docブロックはどういう場所に書くの？
- 2.2 どうやって書くの？
3 Dockブロックの例
4 Dockブロックで使えるタグ
- 4.1 インラインタグ
- 4.2 タグ
5 まとめ

コメントとは？

さて、プログラムを書く上でほぼ全ての言語において、書いたコードに”コメント”を書くことができます。

一般的にはプログラムを書く場合には日本語をかけません。

しかし、コメントには日本語も書けるため、コードの意図がわかりづらい場合や気をつけるべきことをコメントとして書いておくわけです。

また、コメントとして書いた文字は”コメントアウトされている”と表現します。

一時的に実行したくない処理などを”それ一旦コメントアウトして実行してみようか”などと使われたりします。

大抵のエディターではコメントアウトされている箇所は灰色にハイライトされます。

また、コメントを正しくかけていれば通常のプログラムの動作に変化はありません。

ではもうちょっと詳しくみてみましょう！

PHPではコメントアウトする方法が三種類あります。

複数行コメントアウトする場合は/**/で挟んであげ、一行だけのコメントアウトであれば//または#の後ろにコメントを書いてあげればOKです。

さて、コメントの書き方と実際のプログラム上での書かれ方をちらっとみてみましょう！

前半にコメントの使い方の例を、そして後半には実際のコードに対してどのようにコメントが書かれるのかを書きました。

コメントアウトされている場所は灰色になっているのがわかりますね。

最初に複数行コメントアウト、単一行を多用して複数行コメントアウトした例、単一行コメントアウトの使用例、Docブロックでのコメントアウト(後述)をしています。

また、基本形は例の通りですが、コメントの中を記号（------や~~~~や=====など）で枠を彩って綺麗に整形してあるものなど、結構様々なバラエティがあります。

基本的には灰色のところはコメントだ！と思ってもらって大丈夫です。

また、一般的に単一行のコメントアウト//と#は一緒に使われません（みづらいので...）。

どちらかというと他の有名な言語で多く使われているからか、//が多く使われている印象です。

大抵チームやプロジェクト、会社などでどっちか片方に統一されていると思うので、それに従って書きましょう。

また、/**/もあるのですが、こちらは”複数行”をコメントアウトするため、そもそも役割が異なります。

そのため、混在していてもOKです。

コメントについてPHPマニュアルで確認する！

Docコメントとは？

コメントをみているとたまにコメントの中に@マークとかなんか変なものが書かれているものがあります。

また、一見ただの複数行コメントアウトですが、/** */というように、開始のアスタリスクが一つ多いのが特徴です。

/**
  * This is the summary for a DocBlock.
  *
  * This is the description for a DocBlock. This text may contain
  * multiple lines and even some _markdown_.
  *
  * * Markdown style lists function too
  * * Just try this out once
  *
  * The section after the description contains the tags; which provide
  * structured meta-data concerning the given element.
  *
  * @author  Mike van Riel <me@mikevanriel.com>
  *
  * @since 1.0
  *
  * @param int    $example  This is an example function/method parameter description.
  * @param string $example2 This is a second example.
  */

こんな奴ですね。

このような役割をするコメントは各言語によって呼び名が変わってきますが、PHPでは"Docコメント"、”ドキュメントコメント”、”PHPDoc”、"Docブロック"などと呼ばれることが多いです。

すごい簡潔に説明すると、クラスやメソッドの説明をしっかりと書いておこうってやつです。

ただ、人それぞれにバラバラのコメントを書くのもあれだから、少しだけ共通の形式を作って、大まかな形はきめときましょ〜！って感じです。

そうすると全く知らない人が書いたDocコメントでも楽に読むことができるわけです。

また、上記ももちろんなんですが...

実はこれらのコメントからドキュメントを自動生成してくれるんですっ！！！((((；ﾟДﾟ)))))))

つまり、ちゃんと書いておけば比較的楽にメソッドやらファイルやらの情報を書いたドキュメントをいい感じに作ってくれます。

先ほども言った通り、Docコメントにはお決まりの大まかな形があります。

それが事細かに書かれているのがこちら。

phpDocumentor PHPDoc リファレンス

上記内容に則して、本記事では、Dockコメントを”Docブロック”と呼ぶことにします。

Docブロックはどういう場所に書くの？

基本的にクラス、函数=function（メソッド含む）、トレイト、定数やプロパティ等に書くことが想定されているようです。

ただ、押さえておいて欲しいのが

Docブロックは個々の使用箇所ではなく、定義の 構造要素 に記述することを推奨します(RECOMMENDED)
用語集

ということです。

定義の構造要素とかよくわかんない言葉がありますが、ようは値やメソッド、クラス等を使うときじゃなくて、定義するときに書いてあげてね！ってことです。

 /** @var int これはカウンターです。 */
 $int = 0;

 // ここにDocブロックは書けません
 $int++;

たとえとして上記例が挙げられています。

$intを”定義”しているときにはDocブロックを。

そしてその値を使用している箇所ではDocブロックを書かないようにしていますね。

ただ...

変数の定義時にDocブロック書いてあるのはいまだにみたことがない気が...

海外だと使われてたりするのかな・・・？

そんな感じなので、基本的には”メソッドとクラスの定義”に一緒に書いておけば十分でしょう。

どうやって書くの？

さて、それでは書き方を学んでいきましょう！

Docブロックはおおまかに三つの部分に別れています。

以下はphpDocリファレンスからの抜粋です。

1.Summary; a one-liner which globally states the function of the documented element.
要約：文書化された要素の機能についての概要を一行で記述します
2.Description; an extended description of the function of the documented element; may contain markup and inline tags.
説明文：文書化された要素の機能について追加で説明します。文中にマーク付けとインラインタグを含むことができます。
3.Tags; a series of descriptors for properties of this element; such as @param and @return.
タグ：文書化された要素の機能の性質について記述するもので、 @param や @return などがあります。
phpDocumentor - 基本文法 - セクション

このように、要約、説明文、タグの三つの部分に別れています。

では一つづつ解説していきます。

要約

要約セクションでは実際の処理でどんなことをしているのか、簡潔に説明する”動作の概要”を書きます。

バグ修正なんかをするときにDocコメントを流し読みしてて、”あ、ここだな”ってわかりやすい感じに書くといいですね。

要約は”full end(=ドット".")+新しい行”または"連続するふたつの新しい行"で区切ります。

.だけでなく、引き続き改行もないといけないのは、要約内に(.)をつけられるようにするためです。

version情報や"e.g"などの記法にも対応するためだそうです。

また、日本語訳版のphpDocリファレンスの例は正しくないですね。

日本語の末尾に(.)がついてません。

説明文

次に説明文です。

ここでは概要だけでは伝えられない細かい動作や役割なんかについて説明を加えます。

アルゴリズムの解説
コード例
配列の仕様
他の要素との関係
ライセンス情報

といった情報を書いてくださいね〜って書いてありますね。

また、説明文にはインラインタグ(@link等)が使用でき、特殊な情報を書くときに便利です。

Dockブロックの例

では一例を見ていきましょう！

つい先日別の記事にて作成したものに対してつけてみました。

<?php

/**
 * laravelデフォルトページ用コントローラー
 *
 * このファイルではlaravelのデフォルトページで行う処理
 * に関するコントローラーを記載
 *
 * @version 1.0
 * @author Takapon
 * @link http://tektektech.com/php-document-comment
 *
 */

namespace App\Http\Controllers;

use Illuminate\Http\Request;

/**
 * laravelデフォルトページ用のコントローラー
 * 
 * laravelのデフォルトページからの遷移時に使うメソッド群を記載
 */
class TechController extends Controller
{
  /**
   * indexメソッド
   *
   * 簡単な処理を行った後、welcometechページへアクセスする
   *
   * @return Response 	welcometechページの表示
   * @todo 	 $techを入力された値が使えるように
   */
  public function index ()
  {
    /**
     * index内の変数の説明
     *
     * @var string $tech    中央に表示される文字列
     * @var string $script  遷移時に実行されるスクリプト
     */
    $tech = 'てくてくテック';
    $script = '<script>alert("悪さするぞぉ〜？");</script>';

    return view('welcometech', compact('tech','script'));
  }
}

そんなに説明はいらないかなと思いますが簡単にみていきますね。

ちょっとlaravelの要素も入ってるのであれなんですが...

ファイルの説明

/**
 * laravelデフォルトページ用コントローラーのファイル
 *
 * このファイルではlaravelのデフォルトページで行う処理
 * に関するコントローラーを書いています。
 *
 * @version 1.0
 * @author Takapon
 * @link http://tektektech.com/php-document-comment
 *
 */

ここではこのファイルの説明をしています。

ファイルのバージョンはいくつなのか？

誰が書いたのか？

関連する情報のあるリンク

などを書いてます。

リンクはこの記事のものになってますが、例えば本ファイルを作るに当たって議論された内容や経緯などが別の場所にあればそのリンクを。といった使い方が一般的です。

クラスの説明

次にクラスの説明です。

/**
 * laravelデフォルトページ用のコントローラー
 * 
 * laravelのデフォルトページからの遷移時に使うメソッド群を記載
 */
class TechController extends Controller{...}

クラスのdocブロックはクラス定義の直前に書きます。

今回はタグ情報がないですが...ファイル定義と同じくタグに著者情報などを書いたりしてもいいかもしれません。

必要に応じてタグ付け、説明付けをおこなうといいですね。

メソッドの説明

次にメソッドの説明です。

  /**
   * indexメソッド
   *
   * 簡単な処理を行った後、welcometechページへアクセスする
   *
   * @return Response 	welcometechページの表示
   * @todo 	 $techを入力された値が使えるように
   */
  public function index (){...}

メソッドの説明では返り値の説明とtodo（やらないといけないこと）の説明を行っています。

返り値は@return 型説明です。

今回は引数がなかったのですが、引数がある場合は@param 型名変数名説明という体裁でさらにタグを追加すれば大丈夫です。

複数ある場合は合わせて複数書いてあげればOKです。

例えば以下のような感じです。

  /**
   * indexメソッド
   *
   * 簡単な処理を行った後、welcometechページへアクセスする
   *
   * @access public
   * @param  string     $username 入力されたユーザーの氏名
   * @param  int        $userage  入力されたユーザーの年齢
   * @return Response 	welcometechページの表示
   * @todo 	 $techを入力された値が使えるように
   */
  public function index ($username, $userage){...}

変数の説明

最後に変数の説明です。

    /**
     * index内の変数の説明
     *
     * @var string $tech    中央に表示される文字列
     * @var string $script  遷移時に実行されるスクリプト
     */
    $tech = 'てくてくテック';
    $script = '<script>alert("悪さするぞぉ〜？");</script>';

変数宣言が固まっている場合、上記のようにまとめて解説してもいいと思いますが...

バラバラの場合は単一行で書いた方がわかりやすい気がします。

    /** @var string $tech 中央に表示される文字列 */
    $tech = 'てくてくテック';
    /** @var string $script 遷移時に実行されるスクリプト */
    $script = '<script>alert("悪さするぞぉ〜？");</script>';

正直宣言するたびに書いてもちょっと...邪魔かなぁと。

必要そうな場合に書くようにすればいいかなと思います。

Dockブロックで使えるタグ

さて、それでは基本的な書き方を理解した上で、どんなタグがあるのかみていきたいと思います。

以下で様々なタグの詳細を確認できるのでみてみてください。

PHPDoc リファレンス

ただ、日本語ドキュメントはあまりしっかりしていないので、なんとなく訳しつつ解説していきます。

インラインタグ

インラインタグは説明文の中でつかったり、単体でつかってもOKなタグです。

説明文中で(インラインで)使う場合は波括弧"{}"で囲って使います。

@example

@exampleではそのメソッドなどが実際に使われている場所などを示します。

このメソッドどうやってつかうんだろ？って悩んだ時にその場所をみに行けば”ほほーこんな使い方できるんやね”ってなるやつらしいです。

@example [location] [<start-line> [<number-of-lines>] ] [<description>]
or inline
{@example [location] [<start-line> [<number-of-lines>] ] [<description>]}

とありますね。

locationは必須で、相対パス、あるいは絶対パスで指定します。

<start-line>は正のIntegerで指定します。

なくてもOKですが、指定されているExampleとして表示する範囲の開始行を選ぶことができます。

指定されていない場合はファイル全てが表示されます。

<number-of-lines>はstartから何行分を表示するか指定するもので同じく正のIntegerで指定します。

指定されていない場合はstartから末尾までが表示されます。

ただ、執筆時は未実装のようでした。

descriptionは説明書きです。

実際にdocument化したらどうなるか試してみました。

	 @example /Users/taka/MyProject/routes/web.php

タグセクションに記載すると

web.phpファイルが全て表示されてしまいました。

@example /Users/taka/MyProject/routes/web.php 20 ここで使われています。

同じくタグセクションに上記を記載すると

一番上の行でindexと使われているのがわかりやすくなりましたね。

説明文も表示されているのが確認できます。

次に説明文中でインラインで書いてみます。

		/**
		 * indexメソッド
		 *
		 * 簡単な処理を行ってwelcometechページへアクセスする
		 * 具体的な例は{@example /Users/taka/MyProject/routes/web.php 20 ここで使われています。}これ等。
		 */

確かに説明文中に埋め込めましたが...悲惨ｗ

このままだと最後の行まで表示されてしまいます。

そこで<number-of-lines>を使いたいのですが...指定方法がわからず...

@example /Users/taka/MyProject/routes/web.php 20 21 ここで使われています。
@example /Users/taka/MyProject/routes/web.php [20 21] ここで使われています。
@example /Users/taka/MyProject/routes/web.php [20,21] ここで使われています。
@example /Users/taka/MyProject/routes/web.php 20 1 ここで使われています。
@example /Users/taka/MyProject/routes/web.php [20 1] ここで使われています。
@example /Users/taka/MyProject/routes/web.php [20,21] ここで使われています。

色々試したけどうまくいきませんでした...

おそらく現時点でリファレンスページにThe effects of this tag are not yet fully implemented in PhpDocumentor2.と書かれており、まだ未実装の可能性が高いのかなと。

となるとしばらくはインラインでは使わないほうが良さそう。(割と長い間放置されてるみたい...

@exampleのリファレンス(英語）

@internal

このタグは外部での仕様が想定されていない物(メソッドやクラスなど)に対してつけているようです。

例えばパブリックAPIなどに使われる物は外部での仕様も想定されているためこれをつけるべきではないですね。

これを付与することでこの要素はドキュメント化されなくなります。

後ほど説明しますが、@apiタグと少し似ています。

構文は非常に簡単で、

@internal [description]
or inline:
{@internal [description]}}

です。

試した例は以下。

	/**
	 * indexメソッド
	 *
　　　* 簡単な処理を行ってwelcometechページへアクセスする
	 *
	 * @internal このメソッドはインターナルです。
	 */
    public function index (){...}

メソッドが表示されなくなりました。

@internalのリファレンス(英語）

@inheritdoc

まだ公式リファレンス自体書かれてませんでしたので割愛〜！

@link

要素とWebページの関連がある場合にリンクを設定できます。

構文は以下

@link [URI] [<description>]
or inline
{@link [URI] [<description>]}

URIは必ず指定する必要があり、絶対パスでないといけないようです。

<description>も合わせて指定されている場合、その文章がURIに変わってリンクになるようです。

以下試してみました。

		/**
		 * indexメソッド
		 *
		 * 簡単な処理{@link http://tektektech.com/php-document-comment}を行って
         * welcometechページ{@link http://tektektech.com/php-document-comment てくてくテック}
         * へアクセスする
		 *
		 * @link http://tektektech.com/php-document-comment てくてくテック
		 * @link http://tektektech.com/php-document-comment
		 */

インラインで指定したものは説明文の中にリンクが埋め込まれていますね。

また、普通のタグとして指定したものは右のSEE ALSOとして出てきています。

インラインで指定する場合は体裁的に周りを()などで囲み、descriptionはつけておいた方がいいと思います。

文章中にリンクは非常に見辛い...w

@see

このタグは、付与した要素と別の要素、またはURIの関係がある場合に指定します。

例えばindexメソッドに付与した場合、indexメソッドはTechControllerクラスにあるのでそれぞれの要素には親子関係があります。

そういったものを明示的に表してあげるイメージです。

構文は以下

@see [URI | FQSEN] [<description>]
or inline
{@see [URI | FQSEN] [<description>]}

URIには

FQSENとは、"Fully Qualified Structural Element Name"の略で、"Structural Element"(今回はindexメソッドやTechControllerクラスで、Docブロックを適応する対象のようなもの)を参照する場合に使う名前のようです。

例えばindexメソッドなら、namespaceApp\Http\Controllersとクラス名TechController、そしてメソッド名を繋げて、App\Http\Controllers\TechController::index()といった具合らしいんですが...

うまく動作しませんでした...

とりあえず動いた例を。

		/**
		 * indexメソッド
		 *
		 * 簡単な処理{ @see TechController }を行って
		 * welcometechページ{ @see Controller コントローラー }
		 * へアクセスする
		 *
		 * @see Controller コントローラー
		 * @see TechController
		 */

同じ指定をしており、インラインはうまくいってませんが、通常のタグ（SEE ALSO）はちゃんとリンクも繋がっていました。

インラインでの使い方はわからずじまい...

詳しくは以下に少しだけ情報があります。

https://docs.phpdoc.org/glossary.html#term-fqsen

@seeのリファレンス(英)

Namespaceではファイル配置に依存した階層化が行われますが、@packageにつける場合はファイル配置関係なく、意味的に階層化することができますね。（一般的には意味的な階層化になるようにファイル配置の階層も考えられますが。）

指定できる階層の深さには制限はありませんが、推奨されるのは6階層以下だそうです。

たとえば、MVCモデルの場合、各ファイルに(Model, View, Controller)といった３つの論理的な意味が付与できますね。

さらにその中で機能毎に階層化してもいいかもしれないです。

構文は以下

@package [level 1]\[level 2]\[etc.]

バックスラッシュ区切りで最初が第一レベルとなるように書いていきます。

やってみる。

@package PSR\Documentation\API

packageの表示が出るようになりました。

必ずしも階層化せずとも、例えばModel、View、Controllerだけ書くだけでも割とみやすくなるのかなと思います。

あ、このメソッドはModelに書かれてるんだな、ってことは全体的な流れで行くとここら辺かな〜みたいな把握が楽になります。

@packageのリファレンス(英語)

@param

このタグでは引数のメタ情報を明示する場合に使用します。

関数かメソッドで使われ、引数がある場合に型や変数名、簡単な説明を付与できます。

構文は以下です。

@param [Type] [name] [<description>]

型、要素内での変数名、説明です。

使ってみる。

		/**
		 * changeTechメソッド
		 *
		 * @param  string $tech 変更対象の文字列
		 * @return string       変更後の文字列
		 */
		public function changeTech($tech)
		{
			$tech = 'ほげほげテック';
			return $tech;
		}

引数のあるchangeTechメソッドを追加で定義しました。

引数として文字列が入ってきたらそれを別の文字に書き換えて返します。（本来は引数なしで'ほげほげテック'を返すだけでいいので助長ですが...w

実際のプログラムでは引数にstringを書いていないが、こっちでは補完されて表示されていること、Parametersに指定した情報が記載されていることがわかりますね。

メソッドの引数は出来るだけ書いたほうがいいと思います。(ドキュメント化しない場合でも

関数をみて、引数に何を渡せばいい？何が返ってくる？っていうのを一目で理解できるのとできないのとではだいぶん違ってきますので。

@paramのリファレンス(英語)

@property

このタグは先ほどの@methodタグと似たシチュエーションで使うようです。

どのマジックプロパティが渡されるのかをクラスに伝える役割をするみたい？

構文は以下

@property [Type] [name] [<description>]

プロパティの型とプロパティ名、説明ですね。

使ってみる。

@property string hoge プロパティです。

サイドバーにプロパティ情報が追加されました。

@propertyのリファレンス(英語)

@property-read, @property-write

先ほどの@propertyにて、特に、read-only, write-onlyにしたい場合に使うようです。

構文は以下

@property-read [Type] [name] [<description>]
@property-write [Type] [name] [<description>]

@propertyと一緒ですね。

 @property-read string hoge read-onlyのプロパティです。
 @property-write string hoge  wright-onlyのプロパティです。

それぞれ生成されました。

@return

ここではメソッドや関数が返す値などを明示することができます。

これもドキュメント化しない場合でもあったほうがいいタグですね。

構文は以下

@return [Type] [<description>]

返り値の型と説明です。

型は@returnタグをつける場合は必ず指定する必要があります。

説明は必須ではありませんが、例えば連想配列のような複雑な返り値になる場合は書くことが推奨されています。

基本的には全ての関数、メソッドにつけることを推奨されていますが、一部、コンストラクターや返り値がvoidの場合には無視され、その場合はそれぞれ@return self、@return voidと解釈されるようです。

試してみる。

		/**
		 * changeTechメソッド
		 *
		 * @param  string $tech 変更対象の文字列
		 * @return string       変更後の文字列
		 */
		public function changeTech($tech)
		{
			$tech = 'ほげほげテック';
			return $tech;
		}

返り値がある場合に指定したら...

Returnの値についての情報がドキュメント化されました。

また、もしもなかった場合どうなるのかみてみます。

		/**
		 * changeTechメソッド
		 *
		 * @param  string $tech 変更対象の文字列
		 */
		public function changeTech($tech)
		{
			$tech = 'ほげほげテック';
		}

returnがなく、Docには特に何も書かなかった場合(voidの場合)。

returnには特に言及されていませんね。

これが”暗に解釈される”といったかんじかなと。

@returnのリファレンス(英語)

@see

インラインの時に説明したので省略！

@since

このタグは、その要素がどのバージョンから（いつから）使えるようになったのかを示します。

古いバージョンを使っていてあれ？このメソッド使えないな？なんでだ？って最新のリファレンス（自動生成するドキュメント）を見に行くと、あ、最低限このバージョンに更新しないとつかえんのかぁ！

ってわかります。

特に、第三者に公開する場合は強く推奨されると思います。

@since [version] [<description>]

構文は簡単でバージョンと説明です。

@since 1.0.5 2020/10/5

タグにsinceが表示されました。

@subpackage

このタグは廃止予定で非推奨なので、割愛！

@throws

このタグを付与した要素がどんな例外を発生させる可能性があるのかを記述します。

例外が発生した際の場所特定に役に立ちそうかな？

構文は以下

@throws [Type] [<description>]

例外のタイプとどういった場合に想定されるかの説明を書いたりします。

リファレンスからの一例を使って実際に書いてみます。

@throws InvalidArgumentException if the provided argument is not of type 'array'.

例外についての情報が表示されました。

解説文は原文そのままで英語担っています(if the...)が、日本語でも大丈夫です。

@throwsのリファレンス(英語)

@todo

ここでは今後しなければいけないこと（機能の追加や、仕様の変更への対応等）を書きます。

@todo [description]

説明だけですね。

何をどうしなければいけないのか、いつまでにやらなければいけないとかを書いとくといいかもしれないですね。

@todo ユーザからの入力から$techを書き換えてviewへ渡すようにする 2020/04/01までに

Todoをつけれた。

また、@todoタグだと、インラインで説明文中に入れられません。そのため、その場合はTODOマーカーを使うようにすればいいみたいです。

@uses, @used-by

このタグは、他の要素で使われていたり、他の要素を使っていたりする場合に使うようです。

例えば、index()メソッドでchangeTech()メソッドを使っている場合...

index()メソッドのdocブロックには@uses changeTech()、そしてchangeTech()メソッドでは@used-by index()と、それぞれの要素間で使われてる、使ってる関係を示すために使われます。

@seeに少し似ているんですが、oneway(一方向）かtwo-way(双方向)の違いです。

もしも@seeが使われていたら、なるほど、このファイルからそのメソッド使ってるけど、向こうからは使われていないんだな？と、一方向であることを暗に意味しており、双方向であることを意味したい場合に@uses、@used-byが使われます。

@uses [FQSEN] [<description>]

構文はこんな感じです。

どうやら@used-byに関してはドキュメント化する際にphpDocumentorが勝手につけてくれるようです。

が...

んー...いまいちうまく行かない...

FQSENの指定も間違ってない気がするのですが...((((；ﾟДﾟ)))))))

特に変わらないんですよねー。

使い方わかる人がいらっしゃったらコメントお願いします...泣

@uses & @used-byのリファレンス(英語)

@var

このタグはプロパティ、クラス変数の定義時等にそのプロパティの型を明示的に表すことができます。

構文は以下

@var [“Type”] [$element_name] [<description>]

型、プロパティや変数の名前、説明ですね。

また、変数はcompound statements（複数の状態）の可能性があります。

例えば以下。

class Foo
{
  /** @var string|null Should contain a description */
  protected $description = null;
}

$descriptionはstring型かもしれないし、null型かもしれません。

そういう場合は上記のように"|"で区切って書きます。

使ってみた。

/**
 * index内の変数の説明
 *
 * @var string $tech		中央に表示される文字列
 * @var string $script  遷移時に実行されるスクリプト
 */
$tech = 'てくてくテック';
$script = '<script>alert("悪さするぞぉ〜？");</script>';

変数定義時に前置して書きました。

これは特にドキュメント化されるわけではないみたい...?

メソッド以下にいい感じで表示されるのかな〜？とおもったらそうでもありませんでした。

あんまり書きすぎても邪魔になるだけなきがするので、上記例のように、”自明に文字列だ”とわかる場合などは省略したほうがいいでしょう。

型がわかりにくい場所や、間違えると大変な場所に付ける感じでいいのかな？と。

@varのリファレンス(英語)

@version

バージョンタグではそのファイルやクラスの現在のバージョンを示します。

これがあると、外部へ公開した時などにユーザーがバージョン不整合によるメソッド使えない状況などに気付きやすくなりますね。

また、ドキュメント化する場合にはAPI Documentを作る際に利用されるようです。

構文は以下

@version [<vector>] [<description>]

バージョンと説明です。

バージョンはvectorとなっていますが、ようはバージョンのあれです。

こんなやつ1.0.1。

また、このバージョンの付け方にも色々な決まりがあったりして、どの付け方を使うかによって少し変わってきます。

phpDocが推奨しているルールは”Semantic Versioning Standard version 2.0"で、詳細はこちら。

phpDocが推奨するバージョニング（英語）

試してみる

@version 1.0.0

バージョン、出た。

また、 Version Control Systemsを使えば自動でこれらの数値を書き換えてくれる感じにできそうです。

（できないと毎回更新のたびに文字書き換えていくのは骨が折れそうですしね...）

そこらへんの導入は...とりあえず...いいかなｗ

興味がある人は是非調べてみてください。

@versionのリファレンス(英語)

まとめ

思ったより長くなってしまいました...orz

最初はタグの説明はしないつもりだったんですけど気になってしまったのでｗ

ところどころいまいち使い方理解できてないのもありますが、主要なところは説明できたのかなと思います。

全て使ってめちゃめちゃ詳しいコメント欄にする必要はないと思う（むしろ可読性下がるかも...）ので、必要そうなタグだけつけてスリムでリーダブルなコメントを書いてください！

また、リファレンスみたり他のソースを調べたりしながら思ったことなんですが...

githubのリポジトリもほとんど更新が6年前だったり...

案外アップデートされていないんだなぁと...

使うなとまでは言いませんが、あんまり熱を入れて積極的に導入するほどでもないのかなぁ...と。

ただ、今までの慣例からDocブロックがドキュメントコメントとしての体裁として染み付いているので、今後もその体裁が大きく変わることはないと思います。

ドキュメント化は置いておいて、コメントとしてのみ使うのは十分にありかなと思います。

この記事を書いた人

takapon

WEBエンジニアやってます。主にHTML,CSS,JS,PHPあたりが多いです。あとはlaravel, Vue, TypeScriptも。

コメントとは？

Docコメントとは？

Docブロックはどういう場所に書くの？

どうやって書くの？

要約

説明文

タグ

Dockブロックの例

ファイルの説明

クラスの説明

メソッドの説明

変数の説明

Dockブロックで使えるタグ

インラインタグ

@example

@internal

@inheritdoc

@link

@see

タグ

@api

@author

@category

@copyright

@deprecated

@example

@filesource

@global

@ignore

@internal

@license

@link

@method

@package

@param

@property

@property-read, @property-write

@return

@see

@since

@subpackage

@throws

@todo

@uses, @used-by

@var

@version

まとめ