PHPDocのフォーマットまとめ

# はじめに

以下ではコメント記載時の備忘録として、IDEの１つであるVSCodeのツールチップとPHPDoc出力後のイメージを抱き合わせで掲載しています。


# 動作環境

<dl>
    <dt>プラットフォーム</dt>
    <dd>Windows10</dd>
    <dt>PHPDoc</dt>
    <dd>phpDocumentor v3.5.3</dd>
    <dt>IDE</dt>
    <dd>VSCode v1.94.0</dd>
</dl>


# PHPDoc出力コマンド

ファイル構成が以下の場合。
<dl>
    <dt>phpDocumentorの実行ファイル</dt>
    <dd>カレントディレクトリ</dd>
    <dt>ソースファイル</dt>
    <dd>カレントの<code>src</code>ディレクトリ内</dd>
    <dt>PHPDoc出力先</dt>
    <dd>カレントの<code>doc</code>ディレクトリ内</dd>
</dl>

```console:PHPDoc出力時のコマンドライン
> php ./phpDocumentor.phar run -d ./src -t ./doc
```

`phpDocumentor.phar`のファイルは以下のページからダウンロードできます。

https://phpdoc.org/


# 【ヘッダコメント】
<div></div>

## ＜ファイルヘッダ＞

```php:ソース
<?php
/**
 * ファイルのタイトル的なもの
 * 
 * ファイル内容の説明的なもの
 *
 * @license GPL
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 * @author 名前 <my.name@example.com>
 * @copyright 1997-2005 The PHP Group
 */
```

### ・コメントフォーマット

<dl>
    <dt>　ファイルのタイトル的なもの</dt>
    <dd>
        概要を簡潔に１行以内に収めるのが好ましい。
    </dd>
    <dt>　ファイル内容の説明的なもの</dt>
    <dd>説明文や補足的なものを書く。</dd>
</dl>

### ・タグフォーマット

<dl>
    <dt>　＠license [&lt;url&gt;] [name]</dt>
    <dd>
        ファイル単位で書くのが好ましい。<br />
        複数ライセンスの存在があり得る。<br />
        url（省略可能）にはライセンス対象のURLを書く。<br />
    </dd>
    <dt>　＠author [name] [&lt;email address&gt;]</dt>
    <dd>[name]は省略可能。</dd>
    <dt>　＠copyright [description]</dt>
    <dd></dd>
</dl>

### ・出力イメージ

#### 　－ツールチップ－

　なし

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/header-file.png" />

<br />

## ＜クラスヘッダ（親クラスがある場合）＞

```php:ソース
/**
 * 子クラスのタイトル的なもの
 * 
 * 子クラスの説明的なもの
 * 
 * @property string $my_property            子クラス側のプロパティ説明
 * @method string getString()               子クラス側の文字列データ取得メソッドの説明
 * @method void setString(string $data)     子クラス側の文字列データ設定メソッドの説明
 */
class ChildClass extends ParentClass
```

### ・コメントフォーマット

<dl>
    <dt>　子クラスのタイトル的なもの</dt>
    <dd>
        概要を簡潔に１行以内に収めるのが好ましい。<br />
    </dd>
    <dt>　子クラス内容の説明的なもの</dt>
    <dd>説明文や補足的なものを書く。</dd>
</dl>

### ・タグフォーマット

<dl>
    <dt>　＠property [Type] [name] [&lt;description&gt;]</dt>
    <dd>
        <code>__get</code>または<code>__set</code>マジックメソッドが親クラスに存在する場合、有効なプロパティを指定する。<br />
    </dd>
    <dt>　＠method [return type] [name]([[type] [parameter]&lt;, ...&gt;]) [<description>]</dt>
    <dd>
        <code>__call</code>マジックメソッドが親クラスに存在する場合、呼び出し可能なメソッドを指定する。<br />
    </dd>
</dl>

### ・出力イメージ

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-header-class.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/header-class.png" />
　鍵マークが付いているのが親クラスのprivateメンバーです。
　マジックメソッドも含めて親クラスのメンバーと混合で表示されるので注意が必要。

<br />

## ＜関数（またはメソッド）ヘッダ＞

```php:ソース
/**
 * 関数（またはメソッド）のタイトル的なもの
 * 
 * 関数（またはメソッド）の説明的なもの
 * 
 * @since 1.0.2 $type_int引数の追加
 * @since 1.0.1 $type_string引数の追加
 * @since 1.0.0
 *
 * @param string $type_string               文字列データ
 * @param int $type_int                     整数データ
 * @param bool $type_bool                   ブール値（true or false）データ
 * @param float $type_float                 浮動小数点数データ
 * @param object $type_object               型を特定しないインスタンスデータ
 * @param mixed $type_mixed                 型を特定しないデータ
 * @param array $type_array                 配列データ
 * @param callable $type_callable           コールバック
 * @param self $type_self                   自身のインスタンスデータ
 * @return string | null                    文字列データ or null
 * @throws Exception                        ネイティブな例外クラス
 * @throws \Phpdoc\Sample\CustomException   カスタム例外クラス
*/
public function exampleFunction
(
    string $type_string,
    int $type_int,
    bool $type_bool,
    float $type_float,
    object $type_object,
    $type_mixed,
    array $type_array,
    $type_callable,
    self $type_self
)
```

### ・コメントフォーマット

<dl>
    <dt>　関数（またはメソッド）のタイトル的なもの</dt>
    <dd>
        概要を簡潔に１行以内に収めるのが好ましい。<br />
    </dd>
    <dt>　関数（またはメソッド）内容の説明的なもの</dt>
    <dd>説明文や補足的なものを書く。</dd>
</dl>

### ・タグフォーマット

<dl>
    <dt>　＠since [version] [&lt;description&gt;]</dt>
    <dd>
        バージョンに伴う更新履歴。<br />
    </dd>
    <dt>　＠param [Type] [name] [&lt;description&gt;]</dt>
    <dd>
        引数の型、変数名、説明を記載する。<br />
    </dd>
    <dt>　＠return [Type] [&lt;description&gt;]</dt>
    <dd>
        戻り値の型、説明を記載する。<br />
        型はor演算子（'|'）で区切って複数指定可能。
    </dd>
    <dt>　＠throws [Type] [&lt;description&gt;]</dt>
    <dd>
        例外の型、説明を記載する。
    </dd>
</dl>

### ・出力イメージ

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-header-method1.png" />
　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-header-method2.png" />
　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-header-method3.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/header-method1.png" />
　<img src="https://socket-manager.github.io/document/img/php-phpdoc/header-method2.png" />

<br />


# 【プロパティ】
<div></div>

## プロパティ用共通タグフォーマット

<dl>
    <dt>　＠var [Type] [$element_name] [<description>]</dt>
    <dd>
        [Type]データ型。型はor演算子（'|'）で区切って複数指定可能。<br />
        [$element_name]プロパティ名。<br />
        [<description>]データの説明。
    </dd>
</dl>

## ＜文字列（string）型＞

```php:ソース
/**
 * 文章での説明が必要な時はここに書く
 * 
 * @var string | null $type_string 文字列データ or null
 */
public ?string $type_string;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-string.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-string.png" />

<br />

## ＜整数（int）型＞

```php:ソース
/** @var int $type_int 整数データ */
public int $type_int;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-int.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-int.png" />

<br />


## ＜ブール（bool）型＞

```php:ソース
/** @var bool $type_bool ブール値（true or false）データ */
public bool $type_bool;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-bool.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-bool.png" />

<br />


## ＜浮動小数点数（float）型＞

```php:ソース
/** @var float $type_float 浮動小数点数データ */
public float $type_float;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-float.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-float.png" />

<br />


## ＜オブジェクト（object）型＞

```php:ソース
/** @var object $type_object 型を特定しないインスタンスデータ */
public object $type_object;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-object.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-object.png" />

<br />


## ＜型指定なし（mixed）＞

```php:ソース
/** @var mixed $type_mixed 型を特定しないデータ */
public $type_mixed;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-mixed.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-mixed.png" />

<br />


## ＜配列（array）型＞

```php:ソース
/** @var array $type_array 配列データ */
public array $type_array;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-array.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-array.png" />

<br />


## ＜コールバック（callable）型＞

```php:ソース
/** @var callable $type_callable コールバック */
public $type_callable;
```
<br />

### ・出力イメージ
<div></div>

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-property-callable.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/property-callable.png" />

<br />


# 【共通（インライン可能）タグ】
<div></div>

```php:ソース
/**
 * 共通（インライン可能）タグ用
 * 
 * * リスト表示１行目です
 * * リスト表示２行目です
 * 
 * ---
 * 
 * １行目
 * ２行目のつもり
 * 
 * ３行目
 * 
 * ---
 * 
 * # マークダウン１
 * 
 * 親クラスのプロパティ（{@see ParentClass::$items 継承プロパティ}）を継承します。
 * 
 * ## マークダウン２
 * 
 * リンク先のドキュメント（{@link http://example.com/ ドキュメント}）をご覧ください。
 * 
 * ### マークダウン３
 * 
 * @see http://example.com/     ドキュメントのタイトルなど
 * @see ParentClass::$items     関連するクラスプロパティの説明
 * @see ParentClass::setItems() 関連するクラスメソッドの説明
 * @link http://example.com/    リンク先ページ名
 */
protected $items;
```
<br />

### ・マークダウン記法

<dl>
    <dt>　* &lt;description&gt;</dt>
    <dd>
        リスト（箇条書き）で表示可能。<br />
    </dd>
    <dt>　---</dt>
    <dd>横線を引く事が可能。</dd>
    <dt>　# &lt;title&gt;</dt>
    <dd>大きな文字で見出し表示可能。</dd>
    <dt>　## &lt;title&gt;</dt>
    <dd>２番目に大きな文字で見出し表示可能。</dd>
    <dt>　### &lt;title&gt;</dt>
    <dd>３番目に大きな文字で見出し表示可能。</dd>
    <dt>　改行指定</dt>
    <dd>
        空行を挟む事によって改行表示となる。<br />
        空行を挟まない場合は１行とみなされる。
    </dd>
</dl>

### ・タグフォーマット

<dl>
    <dt>　＠see [URI | FQSEN] [&lt;description&gt;]</dt>
    <dd>
        FQSENは完全修飾要素名。<br />
        {}括弧で囲む事によってインライン指定可能。<br />
        [URI | FQSEN]は省略可能。
    </dd>
    <dt>　＠link [URI] [&lt;description&gt;]</dt>
    <dd>
        参考資料等のリンクURIとリンク文字を指定可能。<br />
        {}括弧で囲む事によってインライン指定可能。
    </dd>
</dl>

### ・出力イメージ

#### 　－ツールチップ－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-common1.png" />
　<img src="https://socket-manager.github.io/document/img/php-phpdoc/tooltip-common2.png" />

#### 　－PHPDoc出力－

　<img src="https://socket-manager.github.io/document/img/php-phpdoc/common.png" />

<br />


# おわりに

以前にマインクラフトと連携できるフレームワーク環境を以下の記事でご紹介させて頂きましたが、PHPDocで出力したものをライブラリリファレンスとして公開しています。

https://qiita.com/glasses_seven/items/7a490dc8694348505a53/

ドキュメント類はこちら

https://socket-manager.github.io/document/

今回改めて検証してみてマークダウン記法が使える事には正直驚きましたが、今後は積極的に使っていきたいと思います。
まだ検証できていないタグは他にもありますが、必要に応じて今後も追記していきたいと思います。