PSR-5 PHPDoc Standard

PSR一覧
PSR-5 / PSR-6 / PSR-11 / PSR-12 / PSR-14 / PSR-16

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

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

<?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が複数あった場合の書き方がわからなかったんだけど|区切りでいいんだろうか。