PHPではじめてDoxygenを使った。
高木です。おはようございます。
私は以前からDoxygenをよく使っています。
以前にも書いたと思いますが、クロバーフィールドの就業規則でさえDoxygenで書いているぐらいです。
そんな私でも、Doxygenを使って実際にドキュメント化したことがあるプログラミング言語は限られています。
C、C++、Javaあたりでしょうか？
C++/CLIやC#でさえDoxygenを使った経験がありません。
そんな状況なのですが、このたび初めてPHPでDoxygenを使いました。
何となく
1 2 3 4 | function f(int $arg) : int { ... } |
関数のドキュメントには、f(int $arg)の部分は正しく表示されます。
しかし、末尾の : intが脱落してしまうのです。
PHPで戻り値の型指定ができるようになったのは最近のことなので、まだDoxygenが対応していないだけだと思います。
引数については @param に型を記述しなくてもかまわないでしょうが、@return には型も記述しておいたほうがよさそうです。
まあ、関数の定義をインラインで展開するようにすれば問題ないのかもしれませんが。
今回気付いたのはその2点ぐらいです。
今後はもっといろんなケースを実験していきたいと考えています。
今回は関数だけでコードを書いたため、クラスを一度も使っていません。
PHPのクラスを使った際にどうなるのか、Doxygenの癖をあらかじめ調べておく必要がありますね。
おそらくクラスやインタフェースについては、Javaのそれと変わらない気はしています。
トレイトなんかも是非調べておくべきですね。
名前空間なんかも本当に正しく処理されるのかやや不安があります。
欲をいえば、クラスのマジックメソッドとか、配列で定義したデータ構造なんかもドキュメント化してくれるとうれしいのですが、まあ無理というものです。
このあたりは自分でゴリゴリ書くしかなさそうです。
通信プロトコルで使うデータ・パケットの定義なんかも自分でゴリゴリ書いているので、それと同じようなものでしょう。
ほかには、PHPでC++を前処理するような場合、C++用のDoxygenの記述とPHP用のDoxygenの記述が混在する可能性が出てきます。
たとえば次のようなケースです。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | /** @file test.cc これはテストです。 */ #include <iostream> <?php /** 文字列をシフトJISに変換する。 @param[in] $s 元の文字列 @return 二重引用符で囲んだシフトJISの文字列を返す。 @note エスケープ・シーケンスについては何も処理しない。 */ function to_sjis(string $s) : string { return "\"" . mb_convert_encoding($s, 'SJIS', 'auto') . "\""; } ?> int main() { std::cout << <?= to_sjis('こんにちは世界！'); ?> << std::endl; } |
これがどのように処理されるのか非常に興味があります。
今回はこのあたりにして、続きはまた別の機会に書きたいと思います。