TL;DR

PHP7.1以上のプロジェクトのドキュメントをphpDocumentor2で生成しようとしていませんか？GitHubのREADMEをきちんと読みましょう！

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

事象1 `public const`がダメ？

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

Awesome.php

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

    namespace MyAwesome;

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

対処

検索

StackOverflow「phpDocブロックを2つ置けば解決する」
ググり方が下手なので、これ以外の情報は検索しても出てこなかった

切り分け

定数のdocコメントを消してもダメ

Awesome.php

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

    namespace MyAwesome;

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

定数ごと消すとOK

Awesome.php

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

    namespace MyAwesome;

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

関数は定義してもOK

Awesome.php

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

    namespace MyAwesome;

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

public constをconstにするとOK

Awesome.php

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

    namespace MyAwesome;

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

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

Awesome.php

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

    namespace MyAwesome;

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

原因

オブジェクト定数のアクセス範囲を指定するとダメっぽい…？PHP 7.1から言語機能に追加されたはずでは……

事象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) {
        }
    }

対処

nullableじゃなくしてみる

Awesome2.php

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

    namespace MyAwesome;

    use OtherPackage\OtherClass;

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

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

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から言語機能に追加されたはずでは……

事象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;
            }
        }
    }

対処

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から言語機能に追加されたはずでは……

結論

「No summary was found for this file」というエラーメッセージに騙されましたが、単純にGitHubのREADMEに書いてある通りphpDocumentor2はPHP7.0までしか対応してないという話でした。～完～

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