PSR-5 PHPDoc Standard

[PSR一覧](http://qiita.com/rana_kualu/items/f41d8f657df7709bda0f)
[PSR-5](8b2d9d42b81e9f6f0fd1) / [PSR-6](b37c226363f3015951b6) / [PSR-11](a45829de16380af5acd0) / [PSR-12](28f169bb3eadc6f9e3f3) / [PSR-14](aa60378265d802051397) / [PSR-16](f25ab973b975a274b151)

[PSR5](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md)は、PHPDocの標準フォーマットです。
要するに[Javadoc](https://ja.wikipedia.org/wiki/Javadoc)のPHP版ですね。
まだDraftですが、総論反対が居るとは思えないので、多少の変更はあるかもしれないけど、おそらくそのうちAcceptされるでしょう。
真っ当なフレームワークなら大抵phpDocumentorあたりに従ったコメントが書かれているはずですが、ほぼそのまま使えるようです。
これに従って書いておけば、EclipseやPhpStormあたりで補完が効くようになるでしょう。

英語部分は基本斜め読みなので、なにか間違いがあったら指摘ください。

```php
<?php
/**
 * ファイル単位のコメントは一番上に書く。
 * 
 * 最初に1、2行で概要を書く。1行空けて詳細を書く。
 * さらに1行空けて@***とかを書いていく。
 * @licenseはSPDX(https://spdx.org/licenses/)のIdentifierを指定。
 * 
 * @see https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md @linkはDeprecated.
 * @see ParentClass::fuga() 関連クラスやメソッドも書ける。
 * @see:unit-test \Hoge\Test\Test::getFuga() :を続けることで仕様を拡張できる。PSR5ではその詳細までは定義しない。
 * 
 * @author NurseAngel <ここにメアド>
 * @copyright 2015-9999 コピーライト
 * @license CC0-1.0
 */
namespace Hoge\Fuga\Model;

/**
 * クラスや関数単位のコメントはそれらの直前。
 * 
 * このクラスはダミーなので特に意味のある中身はない。
 * 
 * @package Hoge\Fuga\Model
 * @method void setInt(int $int) 親クラスに__call()がある時に、有効なメソッドを示す。
 * @property int $int 親クラスに__set()、__get()がある時に、有効なプロパティを示す。
 * @uses Parentclass.php
 * @version 1.2.34
 * 
 * @example http://example.com/ 使用例のURI
 * @typedef \ChildClass \OtherClass class_alias('ChildClass', 'OtherClass')したときに指定する？よくわからん。
 */
class ChildClass extends ParentClass
{
    
    /** @var string $str setStringした文字を保存しとく。 */
    private $str = null;
    
    /**
     * 文字列を保存するメソッド。
     *
     * @since 1.2 setString(string $str, \stdClass $class = null) 引数を追加した。
     * @since 1.1 setString(string $str) 実装した。
     * 
     * @param string     $str   セットする文字列。
     * @param \stdClass  $class 特に使わない。
     * @return void 返さない場合はvoid。nullを返す時はnull。
     * @throws InvalidArgumentException
     */
    public function setString(string $str, \stdClass $class = null)
    {
        if(!$str){ throw new InvalidArgumentException(); }
        $this->str = $str;
    }
    
    /**
     * 文字列を取得するメソッド。
     *
     * @return string|null 型が複数ある場合は|で区切って並べる。もしくはmixed。
     */
    public function getString()
    {
        return $this->str;
    }
    
    
    /**
     * APIバージョンを返す。
     * @apiは外部公開APIが前提で、仕様変更が無いかぎり変更しない運用。
     * 
     * @api
     * 
     * @return int バージョン
     */
    public function getApiVersion(): int
    {
        return 1;
    }
    
    /**
     * 内部バージョンを返す。
     * @internalは内部向けで、外からは基本使わないことを現す。@apiの逆。
     * 
     * @internal
     * {@internal 直接解説を書けるが、何故か閉じタグが2個必要}}
     * 
     * @todo @versionから拾いたい。
     * 
     * @return string 内部バージョン
     */
    public function getVersion(): string
    {
        return '1.2.34';
    }
    
    /**
     * @deprecated 1.1:1.3 廃止されたことを示す。:の前は廃止されたバージョン、後は削除される予定のバージョン。
     * @see HOGE::setString()
     * 
     * @param string $str セットする文字列。
     * @return void
     */
    public function _setString($string)
    {
    }
}
```

実際毎回こんなにコメント書いてたら死ぬので、PSR-5完全準拠を詠うFWでも作ってないかぎりここまでやる必要はないと思いますが、
ただ最低でも概要と`@param`、`@return`、`@deprecated`だけは書け。なんとしても絶対に書け。

そういや`@override`がないな。
あと`@throws`が複数あった場合の書き方がわからなかったんだけど|区切りでいいんだろうか。