ツイート
シェア
LINEで送る
B! はてぶでブックマーク
Pocketでブックマーク
RSSフィード

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

php
イラストダウンロードサイト【イラストAC】
の画像をもとに加工しています。

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

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

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

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

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

PSR (PHP Standards Recommendations)

https://www.php-fig.org/psr/

PHP標準勧告。PHPコーディングの標準化を目指す活動のこと。PHP-FIGが策定している。

PHP-FIG (PHP Framework Interop Group)

http://www.php-fig.org/

PHPフレームワーク相互運用グループ。PHPプロジェクトが集まって意見を出し合い、お互いの製品の互換性を調整する団体。

有名なプロジェクトが多く参加している。

規約が決まってないので、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 の書き方として決まっている。

@packageの内容でディレクトリ名の頭を大文字にするというルールで、実際のディレクトリ名を変えろという意味ではない。

ディレクトリ階層
admin
  |- controller
       |- login
            |- default-login.php
コードの階層を@packageにする
<?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, @return を追加
/**
 * 関数の説明
 *
 * @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

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

full-stops.(コロン。半角)
exclamation marks!(半角)
quetion marks?(半角)
行コメントの末尾にどれかを付ける

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

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

エラー
// 行コメントは末尾に気をつける
エラー
// 日本語の文末記号(全角)は使えない。
正解
// かっこ悪いけどコロンを付ける.
// 疑問形もあり----?
// 強調もできる----!

full stop(コロン)は英語表記のルールなので、php Documenter の設定で除外することも多い。

見慣れないこともあるので、full stop という単語がコロンを意味することが分かりづらい。

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と同じ。説明はいりませんね?

前の投稿
WordPressコーディング規約に合わないエラーを直す。ツールでできない所は手作業で。
WordPressの関数・クラスリファレンスの Codex 日本語版は終わりが近づいている。
次の投稿

WordPressの本

post-cta-image

たくさんあるなかで、WordPressの基本が学べる、目的別に学べる本を選びました。

  • WordPressの基本。
  • Webサイト作成から運用まで全体的に学ぶ。
  • かんたんなカスタマイズを学ぶ。
  • 何も分からないところから学ぶ。
  • WordPressからPHPプログラミングを学ぶ。

の5冊です。どうしてもネット上で調べて勉強するのが苦手という人におすすめです。

この内容をモノにすればほかの本は必要ありません。あとは自分の力で、書籍を使わずにインターネット上にある情報だけで学んでいけます。

コメントを残す