APIドキュメントの自動生成について†
- 元タイトル: ソース内ドキュメント、PHPDoc対応にしませんか?
- ページ: BugTrack
- 投稿者: myr
- 優先順位: 普通
- 状態: 提案
- カテゴリー: その他
- 投稿日: 2002-09-15 (日) 13:43:15
- バージョン:
メッセージ†
http://www.stack.nl/~dimitri/doxygen/index.html 仕事でC++のソースとかには使ってます。
PHPも対応してるみたいなので、、、どうでしょうか?
ちょっと確認: PHP向けのソースコードドキュメンテーションシステム†
- phpDocumentor: The complete documentation solution for PHP
- PHPDoc - an adoption of Javadoc to the PHP world
コメント†
- プログラムのドキュメンテーションはやらないとダメですよね。でもdoxygenはやはり日本語マニュアルがないのでちょっと敷居が高いですね。 -- ゆう 2002-09-15 (日) 15:14:17
- すみません。doxygen対応してなかったみたいです(笑)。 PHPDoc http://www.pat.hi-ho.ne.jp/dimension/tips/tips_phpdoc.shtml ってのがあるみたいでした -- myr 2002-09-15 (日) 16:44:53
- 私はPukiWikiによる文芸的プログラミングのほうに興味がありますね～。無茶かなぁ。PukiWikiのプレインテキスト部分にソースを入れて、ページ名でソースかどうかという部分を決めて、ソースだけを切り出すスクリプトを作っておいてってな感じ。 -- kawara 2002-09-15 (日) 23:55:54
- PukiWikiでソースの管理ってことですか?ちょっと心ひかれますね -- ゆう 2002-09-16 (月) 00:37:55
- Doxygenって中間言語みたいなの吐けたと思うんですが、、、もしPHPDocでそれ可能なら、文芸的プログラミングも十分可能では? って的外れな事言ってます? -- myr 2002-09-16 (月) 18:18:13
- PukiWikiでソース管理というか、PukiWikiでドキュメントとソースを含めたページを作ることによって、ドキュメントとソースを同時に管理というイメージですね。 -- kawara 2002-09-16 (月) 20:40:43
- あ、でも、ソースに含まれたコメントからドキュメントを自動生成してくれるPHPDocなどのツールのほうがやっぱり一日の長はあるだろうから、そっちのほうがいいのかなぁ。 -- kawara 2002-09-16 (月) 20:45:09
- 実際にphpDoc形式のコメントを入れたソースを通してみました。下の方を見てください。短いコードなので割とわかりやすいと思います。okkez:memo/改造/UTF-8化/code - okkezのPukiWiki -- okkez
- PEAR ライブラリでは phpDocumentor を採用していますよね。こちらを採用するメリットは、サポートされる出力形式が多いこと、処理が高速なこと、あたりですが、実際みなさまどの程度採用されているかは良く知りません。私は phpDocumentor を使っています。phpDocumentor のページには「PHPDoc とも呼ばれている」と書いてありますが、通常 PHPDoc と呼ばれるものとは別ものだと思います……。 :p こちらを採用されてはいかがでしょうか。 -- kawai
- ツッコミありがとうございます。双方の情報を上に追記しておきました。 -- henoheno
- http://fullmetal.dip.jp/doc/ でちょこちょこコメント付けてドキュメント化してます。まだ途中ですが、無いよりマシなレベルにはなってきたと思います。手伝ってくれる人募集します。*1 -- okkez
- 美しいですねぇ～ :) -- teanan
- もちろん募集は自由です :) この中で一番の経験者は okkez さんなので、今までの経験を踏まえたポイントなど教えていただけると、検証する側として助かります :) コンセプトに沿ったコメントをさらに追加できるならば追加したいし、より効果的なドキュメントを生成できるいけてる工夫があればそれを検討したいです :) -- henoheno
- コメント付けのコンセプトは、
- プラグイン作者がどの関数を使えるのかわかるようにすること
- また、クラスや関数の使い方が簡単にわかるようになること
- これから開発に参加する人が、全てのソースコードを読まなくても概略がわかるようにすること
ですね。
今、どうしようかと思っているのは、
- プラグインのパッケージ名*2
- 関数のアクセス権限*3
- クラス変数/インスタンス変数の役割
です。 -- okkez
- この件に関して、okkezさんから、phpDocumentorのコメント入りのソースを受け取りました。今後teananさんと順次適用して行くと思います。 -- henoheno
- phpDocumentorは現在ではZendStudioとも連携するようになっています*4。今までのokkezさんの行動も考慮するに、phpDocumentorを採用するのが自然な流れでしょう。 -- henoheno
- 利点について。(1) 利用者にとって、PukiWikiソースの内部で定義されている関数を探しやすくなるかもしれない (2)少なくとも関数ヘッダーの様式が統一され、読み易くなるかもしれない -- henoheno
- 欠点について。導入当初、ソースの差分が膨大に発生するので、コードのチェックが大変になる。そのため、できればこの件に関する修正はリリース作業の終盤にまとめて行うのが理想です。しかし前に進めるためならそれ以外のタイミングでも問題ありません。 -- henoheno
![[PukiWiki]](image/pukiwiki-dev.png "[PukiWiki]")
