PHPerのための「PHPDoc相談会」PHPTechCafe
=============================================

# PHPer's NEWS

::: info
**[PHPでGraph APIを操作できる「Microsoft Graph PHP SDK 2.0.0-RC5」が登場](https://codezine.jp/article/detail/16164)**

:::

::: info
**[【PHP8.2】PHPで選言標準形 (Disjunctive Normal Form) 型が使えるようになる](https://qiita.com/rana_kualu/items/ddadd32756afdefbe99f)**

:::

::: info
**[小学6年生が将来就きたい職業、男子では「エンジニア」が5位に](https://news.mynavi.jp/article/20220708-2393089/)**
将来就きたい職業ランキングでユーチューバーに勝ててうれしい
:::

::: info
**[【PHP8.2】PHP8.2の新機能](https://qiita.com/rana_kualu/items/fc4b02e2daaf102aa92f)**

:::

::: info
**[PHPカンファレンス沖縄、タイムテーブル公開＆参加申し込み受付開始](https://phpcon.okinawa.jp/)**
テーマが幅広い！
:::

::: info
**[PHPカンファレンス2022も参加申し込み受付開始](https://phpcon.connpass.com/event/255324/)**
今回はDiscordがないので語りたい人は現地に行くしかないですね。
:::

::: info
**[Slim 4.10.0 released](https://www.slimframework.com/2022/03/14/slim-4.10.0-release.html)**

:::

::: info
**[PHP Annotated – July 2022](https://blog.jetbrains.com/phpstorm/2022/07/php-annotated-july-2022/)**
毎月発行されている模様。
PHP8.2 の記事はもちろん、 php.net のデザインアップデートの記事 も気になりました。
:::

::: info
**[PHP 8.2.0 Beta 1 available for testing](https://www.php.net/archive/2022.php#2022-07-21-1)**

:::

::: info
**[PhpStorm Plugins You Should Know](https://levelup.gitconnected.com/phpstorm-plugins-you-should-know-ea4e51aeee69)**

:::

# 特集 ～PHPDoc相談会～

PHPDocについてのありそうな質問を上げて、回答についてわいわい盛り上がる

## 前回のおさらい

https://hackmd.io/VkWCZxQbT5yL8iO3t6TegA?view

## PHPDocに関する質問

### 最低限書いておきたいコメントはなになのか？
* 必須？
* @var
* @param
* @return
* @throws　明示的にthrowしてるなら
* 微妙？
* @uses & @used-by
* https://tech.excite.co.jp/entry/2021/09/24/102021
* あまりいらなそう。
* メリットが未使用関数の検知、定義ジャンプとかができるようになること
* IDEのプラグインでいけるのでは？
* @package
* 参考資料
* https://tech-blog.rakus.co.jp/entry/20210326/php
* https://zonuexe.github.io/phpDocumentor2-ja/references/phpdoc/index.html
* https://qiita.com/motoyan-qwt/items/ee973666f1105435822c

### [phpDocumenter](https://phpdoc.org/) 使ってますか？

* PHPのプロジェクトのドキュメントを自動で作成してくれるツール
* 基本的なPHPDocコメントだけでも書けていればかなり有効な気がする
* CIに組み込めばドキュメントのメンテコストも削減できそう

### 戻り値がvoidの場合、@return voidは書いた方がいいか？

* https://stackoverflow.com/questions/2061550/phpdoc-return-void-necessary
* [PHPで型定義されている場合、PHPDocでも型を書いた方がいいか？](https://stackoverflow.com/questions/66109834/in-phpdoc-is-it-neccessary-to-define-parameter-type)

### @throws \Throwableは書くべき？

* PhpStormでwarningが出るときと出ないときがある。

### 各IDEでサポートしているPHPDocがわからない
* PhpStorm
* PHPDocに関する公式記載は[こちら](https://pleiades.io/help/phpstorm/phpdoc-comments.html#64d47e38)
* 公式でも特に触れられていない
* VSCodeの拡張
* [PHP DocBlocker](https://marketplace.visualstudio.com/items?itemName=neilbrayfield.php-docblocker)
* PHPDoc入力の補助のみ
* [PHP Intelephense](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client)

### PhpStormは、配列内の型、連想配列の key & value の型を検知してくれる？

* [型を使いこなすためのPHPDocの書き方](https://tech-blog.rakus.co.jp/entry/20210326/php#%E5%A4%9A%E3%81%8F%E3%81%AE%E3%83%84%E3%83%BC%E3%83%AB%E3%81%A7%E6%9C%89%E5%8A%B9%E3%81%AAPHPDoc%E3%81%AE%E6%9B%B8%E3%81%8D%E6%96%B9:~:text=%E3%82%8C%E3%81%BE%E3%81%9B%E3%82%93%E3%80%82-,%E9%85%8D%E5%88%97%E5%9E%8B,-PHPDoc%E3%81%A7%E9%85%8D%E5%88%97)
* [楽をするためのPHPDocと配列型の落とし穴](https://speakerdeck.com/takaram/phpdoc-and-pitfalls-of-array?slide=24)

→ 型の検知はまだ。
キー名の検知は2020.3以降のバージョンでサポートしている(ArrayShape)。
2022.1以降ではさらに、ネストされた連想配列もサポートしている。

* [release note](https://www.jetbrains.com/ja-jp/phpstorm/whatsnew/)
* [使用方法](https://github.com/JetBrains/phpstorm-attributes#arrayshape)

### レガシーシステムとPHPDocの向き合い方

* 型エラーになるわけでもないので、どんどんDocを書いていったほうがいいのかも？
* PHPDocは静的解析と相性がいいが、そもそもレガシーシステムに静的解析を入れるのが大変
* https://fortee.jp/phperkaigi-2021/proposal/35177e2b-189c-43c2-ad29-e74caf5033e7

### ほかの言語のDocコメントとの違い

* JavaDoc
* 1行目の要約は「.」で終わらせる？
* 調べる限りではJavaDocコメントに規約のようなものは見当たらない
* Python
* [Pythonのドキュメントコメントは派閥的なものがある](https://qiita.com/oyan29/items/42c7ebbd98d02c1a2933)
* PHPDocもしっかりと決まったルールがあるわけではない
* [補足資料](https://devblog.thebase.in/entry/2019/12/14/110000)