PHP_CodeSniffer で “Missing file doc comment” エラーが消えない場合の対処法

問題

VSCode に phpcs プラグインを導入¹して WordPress PHP コーディング規約に PHP コードが準拠しているかのチェックを行っているのだが、以下のようなコードで、“Missing file doc comment” エラーが消えない場合がある。

<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <[e-mail]>
 * @license    https://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3
 * @link       https://example.com
 * @since      1.0.0
 */

require_once ABSPATH . 'wp-admin/includes/plugin.php';

// 以下略

確認してみると、どうやら require_once² が原因となっているようである³。

File doc comment 直後の関数宣言に doc comment がない場合にも “Missing file doc comment” エラーが出るようで⁵、require_once が関数宣言に類するものとして扱われているのではないかと思われる⁶。

当然ながら require include include_once でも同様の問題が発生する。

対処法 1（PHP 終了タグ & 開始タグを挿入）

File doc Comment と require once の間に PHP 終了タグと開始タグを挿入することで、エラーが出なくなる模様⁷。

<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <[e-mail]>
 * @license    https://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3
 * @link       https://example.com
 * @since      1.0.0
 */

?>
<?
require_once ABSPATH . 'wp-admin/includes/plugin.php';

// 以下略

対処法 2（なんらかのコメント挿入）

上記のように、（関数宣言に類するものとみなされているらしき）require_once の前に doc comment がないことが原因なので、なんらかのdoc comment を file doc comment と require_once の間に挿入することでも、エラーは解消される。

<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <[e-mail]>
 * @license    https://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3
 * @link       https://example.com
 * @since      1.0.0
 */

/**
 * なんらかのコメント
*/
require_once ABSPATH . 'wp-admin/includes/plugin.php';

// 以下略

対処法 3（require_once の記述位置を変更する）

require するファイルが file doc comment の直後で必要でないのなら、必要な箇所の直前に記述位置を変更することでも対処可能。

<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <[e-mail]>
 * @license    https://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3
 * @link       https://example.com
 * @since      1.0.0
 */

// なんらかのコード

require_once ABSPATH . 'wp-admin/includes/plugin.php';
if ( is_plugin_active( 'some-plugin/some-plugin.php' ) ) {
	// 略
}

// 以下略

対処法 4（require_once を即時関数で囲む）

冒頭で require したくて、とくにコメントも思いつかないなら、即時関数で囲むことでもエラーが回避できるし、問題なく動いた。いっそ場合によっては、file doc comment 以下すべてを即時関数で囲んでやってもいいかもしれない。

<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <[e-mail]>
 * @license    https://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3
 * @link       https://example.com
 * @since      1.0.0
 */

( function() {
	require_once ABSPATH . 'wp-admin/includes/plugin.php';
} )();

// 以下略

1. Cf. VSCodeで「WordPress Coding Standards」に準拠してPHPの自動フォーマットする方法 | HPcode ↩

2. Cf. PHP: require_once - Manual ↩

3. 今回この問題が発生した例では、プラグインが導入されているか否かを is_plugin_active()⁴ で確認するために、pluguin.php を読み込んでいる。 ↩

4. Cf: 関数リファレンス/wp enqueue script - WordPress Codex 日本語版 ↩

5. Cf. drupal - Missing file doc comment? - Stack Overflow ↩

6. 以下のいずれの対処法でも、関数宣言の doc comment 欠如にかんしても “Missing file doc comment” が消えたため（当然 “Missing doc comment for function” エラーは出るが）、この推測はおそらく正しい。 ↩

7. Cf. Missing file doc comment · Issue #693 · WordPress/WordPress-Coding-Standards ↩