WordPress, phpcsが出すコメント（phpDoc）のエラーを直す。

WordPressにはコーディング規約があります。phpcsでチェックすることができ、コメントに関するエラーもたくさん出ます。

コメントを強制的に規約で書かせるのはWordPress独特の規約です。ちなみに、スタンダードなPSRはコメントに関する規約はゆるゆる。

WordPressはコメントに厳しい。PSRはまだ決まっていない。

PHPのコーディング規約は一般的にPSRを使います。PSRはPHPで開発しているたくさんのプロジェクトが集まってコーディングの共通化を図る団体で、スタンダードなPHPコーディング規約と言っても過言じゃありません。

PSRはかなり早い段階でphpDoc、コメントの規約も用意していたんですが長年ドラフトのまま。一向に公開される気配がない。

規約が決まってないので、phpcsをPSRでチェックしてもコメントについてはエラーが発生しません。極論を言えばコメントなしでも良い。

一方、WordPressでは、コメントを書くように規約で強制しています。今回、紹介するエラーの内容はWordPress規約でphpcsを実行したときに出るもの。

ちなみにphpcsは、PHP_CodeSnifferというPHPコーディングの静的チェックをする有名なツールコマンドのこと。

Missing file doc comment

いきなり1行目から出るやつです。1行目はだいたい '<?php' しか書かないものなんですが、PHPコードを明示するルールでエラーが出られると、どうしていいか分からないですよね？

これはphpDocのファイル説明のコメントを追加しましょう。という意味。

<?php

<?php
/**
 * ここにファイル説明を書く
 */

You must use "/**" style comments for a file comment

ファイル説明のドキュメントは使うコメントが決まっています。

<?php
// ファイル説明を書く

<?php
/*
 * このコメントもまちがい
 */

<?php
/**
 * ファイルドキュメントのコメントは決まっている
 */

このコメントの下に必ず空行を入れて下さい。これもフォーマットの1つです。

このドキュメントルールは、functionでも同じ。

Missing @package tag in file comment

ファイルドキュメントにはいくつか付けなきゃいけないタグがあります。@packageもそのひとつ。

ちなみに、WordPressのコーディング規約である WordPress Coding Standartds は @package だけで治る。

<?php
/**
 * ファイルの説明
 */

<?php
/**
 * ファイルの説明
 *
 * @package Admin
 */

@package 以外のタグが必要になっても、エラーメッセージとしては同じようなものです。足りないタグを修正していけば問題ない。

@since とかよく使われますね？

@package の書き方

@packageはファイルがアプリケーションのどの部分になるかを書きます。

まず間違いないのは namespace の内容を入れること。ただし、階層の '\' を '_' に変えて書きます。

<?php
/**
 * テストコントローラー
 *
 * @package Admin_Controller_Test
 */

namespace Admin\Controller\Test;

クラスを使ってないときはソースコードのディレクトリ階層を使うのが吉。

URLパスの階層を使ったりもしますがURLは変わることがあるし、アプリの中身を隠蔽するためにあえて階層化しないこともある。

それに比べソースコードの階層はそうそう変わりません。まぁこの辺は、何を書くかの独自ルールがあったりするのでそれに合わせましょう。

決めてくれとなれば繰り返しますがソースコードの階層を使う。ちなみに、この階層区切りも '_' を使います。

またディレクトリ名の頭は大文字です。この2つは @package の書き方として決まっている。

admin
  |- controller
       |- login
            |- default-login.php

<?php
/**
 * デフォルトログイン
 *
 * @package Aamin_Controller_Login
 */

Missing doc comment for function xxxxx()

function でも説明が必要です。それがないとこのエラーが出る。

/**
 * 関数の説明
 */
function xxxxx( $param1, $param2 ) {
	return true;
}

さっきも言ったように、function はコメントの形式が決まっています。それを守らないと今度は " You must use "/**" style comments for a file comment " が出ます。

Doc comment for parameter "$xxxxx" missing

functionでも必須のタグがあります。パラメータがあるときの @param もそう。functionは @param と @return が付いていれば問題ありません。

（return がなければ省略可。パラメータもなければ説明文だけで良い。）

/**
 * 関数の説明
 */
function xxxxx( $param1, $param2 ) {
	return true;
}

/**
 * 関数の説明
 *
 * @param string $param1 first parameter
 * @return bool
 */

Parameter comment must end with a full stop

パラメータのコメントの説明は文末記号が必要です。コロン（.）。英語表記なので半角。

日本語では違和感があるかもしれませんが、あまりに数多くのエラーが出るとその他のエラーが見えなくなるので、付けときましょう。

/**
 * 関数の説明
 *
 * @param string $param1 first parameter.
 * @return bool
 */

@param は、データ型、変数、説明を半角スペースで区切って書きます。@return はデータ型だけを書くのが一般的。

Missing parameter comment

functionのパラメータでこういう書き方を見たことないでしょうか？

/**
 * 関数の説明
 *
 * @param string $param1
 *          first parameter.
 * @return bool
 */

パラメータの説明だけは次行に書くタイプ。これも正解です。経験則ではこっちのほうが多いかな？

ただこのタイプは、php Documenterの設定で許さないこともあり、書き方がはまらないと "Missing parameter comment" が発生します。

直し方はかんたん。1行でダメなら2行、2行でダメなら1行にするだけ。

ちなみにWordPressでは1行がルールです。

Inline comments must end in full-stops, exclamation marks, or question marks

インラインコメントとは、'//' を使った行コメントのこと。このコメントでは文章終わりの記号を付けてくださいって言ってます。

このルールは英語表記になっているので、『。』や『！』『？』など全角では治りません。

日本語コメントの後ろに英語表記の記号を付けるのはかっこ悪いですが、あまりにエラーが出るようなら鬱陶しいし、他のエラーを見落としてしまいます。付けてしまいましょう。

// 行コメントは末尾に気をつける

// 日本語の文末記号（全角）は使えない。

// かっこ悪いけどコロンを付ける.
// 疑問形もあり----?
// 強調もできる----!

Missing doc comment for class Xxxxx

最後にクラスオブジェクトについて。

PHPでは1ファイルに定義できるクラスは1つだけです。2つのクラスを実装してもエラーではありませんが。

1ファイル・1クラスなので、クラスドキュメントを書いてさえいれば、ファイルドキュメントはいらないことも多いです。

もちろん、両方書いても良い。書く内容はちがうので。

クラスドキュメントは説明文だけで良いことも多いです。@の付くタグ不足のエラーが出ればそれを追記すればいいだけなので難しくありません。

<?php
namespace Test\Lib;

use Lib\Util\Singleton;

class Test {
}

<?php
namespace Test\Lib;

use Lib\Util\Singleton;

/**
 * テストクラス
 */
class Test {
}

クラスドキュメントのコメントも "/**" から始めます。

Missing member variable doc comment

このエラーはクラス内のプロパティのコメントが抜けているときに発生します。コメントの形式はクラスやfunctionと同じで "/**" で始める。

<?php
namespace Test\Lib;

use Lib\Util\Singleton;

/**
 * テストクラス
 */
class Test {

    /**
     * シリアルID
     */
    private $serial_id;
}

Missing @var tag in member variable comment

クラスのプロパティは説明文だけでは足りません。@var が必要です。データ型と説明文を半角スペースで区切ります。

<?php
namespace Test\Lib;

use Lib\Util\Singleton;

/**
 * テストクラス
 */
class Test {

    /**
     * シリアルID
     * @var string serial id
     */
    private $serial_id;
}

@var はfunctionの @param みたいなものなんですが、文末記号のコロンはいりません。この辺のちがいが分からない。

php Documenter の設定なのかもしれません。

There must be exactly one blank line before the tags in a doc comment

このエラーは @var とプロパティの説明文に間に1行の空白がないと出ます。

さっきの書き方はエラーになる。

正解はこちら。

<?php
namespace Test\Lib;

use Lib\Util\Singleton;

/**
 * テストクラス
 */
class Test {

    /**
     * シリアルID
     *
     * @var string serial id
     */
    private $serial_id;
}

このエラーはfunctionの説明文と @param, @return の間にも1行空いてないと出るし、ファイルドキュメントの説明文と @package の間が空いてないと出ます。

説明文と@の付いたタグは1行空けるというのがルール。

最後にメソッドなんですが、メソッドは通常のfunctionと同じ。説明はいりませんね？