環境
初書:2020/09/03
PC:macOS 10.15.6
Composer: v1.10.10
phpDocumentorとは
phpDocumentor 2は、PHPソースコードから直接ドキュメントを生成できるようにするツールです。 これにより、ユーザーインターフェイスから利用できるものだけでなく、ソース内に埋め込まれた機能に関する詳細情報を消費者に提供できます。
(https://www.phpdoc.org より。google翻訳による訳)
要するに、自動ドキュメント生成ツールである。
phpファイルの中に、phpdocでコメントを記述していれば、それを元にドキュメントを作成してくれる便利ツールです。
前から気になってはいたものの、ダウンロードが難しそうで断念していたが、ひょんな事からComposerをダウンロードしたので使ってみることにした。
ダウンロード方法
composerを使う(composerは依存関係を多く使うので不便な方は注意とのこと)
% composer require --dev phpdocumentor/phpdocumentor
phpDocumentorは開発環境でしか使わないよね。っていうことで--devをつける。
なんか十数行の警告があったがほんの数秒でDL完了!
(今作ってるプログラムはComposer未使用だったので、composer関連のファイルが大量に作成された。。)
使ってみる
% vendor/bin/phpdoc run -d dir1 -t dir2
-dの後ろのdir1は、生成したいphpファイルがあるフォルダ(の相対パスもしくは絶対パス)
-tの後ろのdir2は、出力したいフォルダ
ちなみに結構フォルダやファイルが作成されるので、-tの後ろは専用のフォルダを作ったほうがいいと思う。
表示してみる
さっき作ったdir2のindex.htmlにアクセスすると表示される。
・・・いや、表示されない。
どうやらコンパイルエラーでほとんどのファイルが生成に失敗したらしい。(右上にあるReports->Errorsでエラー内容を見れる)
No summary was found for this file
・・・いや今まで書いてきたのはなんだったのか。
とりあえず、何かしら書き方が間違っているようなので、コードを見直してみることにする。
(多分ファイルの概要を書いていないからエラーが出たのかと)
終わり
分かりやすく書かないと作成しても読めないという事実。
あとはアップデートする場合は上記コマンドの実行でいいのだろうか?(未確認)
追記。
ファイル概要を書いてないのでエラーが出たのは間違い無いのだが、
php7.4の書き方にそもそも対応していないらしく、クラス内変数に型宣言するとエラーを吐く。
phpDocumentorのためにバージョンを下げた書き方をするわけにもいかないので、お預けかもしれない。