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

## 問題

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

[^phpcs]: Cf. [VSCodeで「WordPress Coding Standards」に準拠してPHPの自動フォーマットする方法 | HPcode](https://haniwaman.com/vscode-wordpress-format/)

``` PHP
<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <foo.bar@example.com>
 * @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`[^require_once] が原因となっているようである[^plugin.php]。

[^require_once]: Cf. [PHP: require_once - Manual](https://www.php.net/manual/ja/function.require-once.php)
[^plugin.php]: 今回この問題が発生した例では、プラグインが導入されているか否かを `is_plugin_active()`[^is_plugin_active] で確認するために、pluguin.php を読み込んでいる。
[^is_plugin_active]: Cf: [関数リファレンス/wp enqueue script - WordPress Codex 日本語版](https://wpdocs.osdn.jp/%E9%96%A2%E6%95%B0%E3%83%AA%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B9/wp_enqueue_script)

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

[^drupal]: Cf. [drupal - Missing file doc comment? - Stack Overflow](https://stackoverflow.com/questions/32456325/missing-file-doc-comment)
[^function]: 以下のいずれの対処法でも、関数宣言の doc comment 欠如にかんしても “Missing file doc comment” が消えたため（当然 “Missing doc comment for function” エラーは出るが）、この推測はおそらく正しい。

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

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

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

[^github]: Cf. [Missing file doc comment · Issue #693 · WordPress/WordPress-Coding-Standards](https://github.com/WordPress/WordPress-Coding-Standards/issues/693)

``` PHP
<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <foo.bar@example.com>
 * @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
<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <foo.bar@example.com>
 * @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
<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <foo.bar@example.com>
 * @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
<?php
/**
 * ファイルのタイトル
 *
 * ファイルの説明.
 *
 * @category   Components
 * @package    WordPress
 * @subpackage テーマ名
 * @author     名前 <foo.bar@example.com>
 * @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';
} )();

// 以下略
```