Edited at

PSR-5 PHPDoc Standard

More than 1 year has passed since last update.

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