phpDocumentorでNo summary was found for this file.

# TL;DR
PHP7.1以上のプロジェクトのドキュメントをphpDocumentor2で生成しようとしていませんか？[GitHubのREADME](https://github.com/phpDocumentor/phpDocumentor#phpdocumentor-v2-stable)をきちんと読みましょう！

以下そこにたどり付くまでの記録です。

## 事象1 `public const`がダメ？
以下のファイルを`phpDocumentor`に突っ込むと`No summary was found for this file`というエラーが出る

```php:Awesome.php
<?php
    /**
     * AwesomeなClassを定義するファイル
     */

    namespace MyAwesome;

    /**
     * AwesomeなClass
     */
    class Awesome {
        /**
         * PO は HOGEHOGE とする
         *
         * @var string
         */
        public const PO = "HOGEHOGE";
    }
```

### 対処
#### 検索
[StackOverflow](https://stackoverflow.com/questions/21312643/phpdoc-no-summary-found-for-this-file)「phpDocブロックを2つ置けば解決する」
ググり方が下手なので、これ以外の情報は検索しても出てこなかった

#### 切り分け
:x:定数のdocコメントを消してもダメ

```php:Awesome.php
<?php
    /**
     * AwesomeなClassを定義するファイル
     */

    namespace MyAwesome;

    /**
     * AwesomeなClass
     */
    class Awesome {
        public const PO = "HOGEHOGE";
    }
```

:o: 定数ごと消すとOK

```php:Awesome.php
<?php
    /**
     * AwesomeなClassを定義するファイル
     */

    namespace MyAwesome;

    /**
     * AwesomeなClass
     */
    class Awesome {
    }
```

:o: 関数は定義してもOK

```php:Awesome.php
<?php
    /**
     * AwesomeなClassを定義するファイル
     */

    namespace MyAwesome;

    /**
     * AwesomeなClass
     */
    class Awesome {
        /**
         * po は HOGEHOGE
         *
         * @return string
         */
        public function po(): string {
            return "HOGEHOGE";
        }
    }
```

:o: `public const`を`const`にするとOK

```php:Awesome.php
<?php
    /**
     * AwesomeなClassを定義するファイル
     */

    namespace MyAwesome;

    /**
     * AwesomeなClass
     */
    class Awesome {
        const PO = "HOGEHOGE";
    }
```

:o: `public`を消すとdocコメントを付けてもOK

```php:Awesome.php
<?php
    /**
     * AwesomeなClassを定義するファイル
     */

    namespace MyAwesome;

    /**
     * AwesomeなClass
     */
    class Awesome {
        /**
         * PO は HOGEHOGE とする
         *
         * @var string
         */
        const PO = "HOGEHOGE";
    }
```

### 原因
オブジェクト定数のアクセス範囲を指定するとダメっぽい…？[PHP 7.1](https://www.php.net/manual/ja/language.oop5.constants.php)から言語機能に追加されたはずでは……

## 事象2 `nullable`な引数がダメ？

以下のファイルを`phpDocumentor`に突っ込むと`No summary was found for this file`というエラーが出る

```Awesome2.php
<?php
    /**
     * Awesome2 を定義するファイル
     */

    namespace MyAwesome;

    use OtherPackage\OtherClass;

    /**
     * Awesomeなclassその2
     */
    class Awesome2 {
        /**
         * 何もしないコンストラクタ
         *
         * @param OtherClass|null $other
         */
        public function __construct(?OtherClass $other) {
        }
    }
```

### 対処
:o: nullableじゃなくしてみる

```Awesome2.php
<?php
    /**
     * Awesome2 を定義するファイル
     */

    namespace MyAwesome;

    use OtherPackage\OtherClass;

    /**
     * Awesomeなclassその2
     */
    class Awesome2 {
        /**
         * 何もしないコンストラクタ
         *
         * @param OtherClass $other
         */
        public function __construct(OtherClass $other) {
        }
    }
```

:o: デフォルト引数を指定してみる

```Awesome2.php
<?php
    /**
     * Awesome2 を定義するファイル
     */

    namespace MyAwesome;

    use OtherPackage\OtherClass;

    /**
     * Awesomeなclassその2
     */
    class Awesome2 {
        /**
         * 何もしないコンストラクタ
         *
         * @param OtherClass|null $other
         */
        public function __construct(OtherClass $other = null) {
        }
    }
```

### 原因
`nullable`な型指定がダメっぽい…？[PHP 7.1](https://www.php.net/manual/ja/migration71.new-features.php)から言語機能に追加されたはずでは……

## 事象3 `nullable`な返り値がダメ？

以下のファイルを`phpDocumentor`に突っ込むと`No summary was found for this file`というエラーが出る

```Awesome3.php
<?php
    /**
     * Awesome3 を定義するファイル
     */

    namespace MyAwesome;

    /**
     * Awesomeなclassその3
     */
    class Awesome3 {
        /**
         * 名前を検証する
         *
         * @param string $name
         * @return string|null
         */
        public function validate(string $name): ?string {
            if($name === "po"){
                return null;
            }else{
                return $name;
            }
        }
    }
```

### 対処
:o: `mixed`にしてみる

```Awesome3.php
<?php
    /**
     * Awesome3 を定義するファイル
     */

    namespace MyAwesome;

    /**
     * Awesomeなclassその3
     */
    class Awesome3 {
        /**
         * 名前を検証する
         *
         * @param string $name
         * @return string|null
         */
        public function validate(string $name) {
            if($name === "po"){
                return null;
            }else{
                return $name;
            }
        }
    }
```

### 原因
`nullable`な型指定がダメっぽい…？[PHP 7.1](https://www.php.net/manual/ja/migration71.new-features.php)から言語機能に追加されたはずでは……

# 結論
「No summary was found for this file」というエラーメッセージに騙されましたが、単純にGitHubのREADMEに書いてある通り[phpDocumentor2はPHP7.0までしか対応してない](https://github.com/phpDocumentor/phpDocumentor#phpdocumentor-v2-stable)という話でした。～完～

おとなしくphpDocumentor3を待ちましょう。今RC版までリリースされています。