APIドキュメントの自動生成について

  • 元タイトル: ソース内ドキュメント、PHPDoc対応にしませんか?
  • ページ: BugTrack
  • 投稿者: myr
  • 優先順位: 普通
  • 状態: 提案
  • カテゴリー: その他
  • 投稿日: 2002-09-15 (日) 13:43:15
  • バージョン:

メッセージ

http://www.stack.nl/~dimitri/doxygen/index.html 仕事でC++のソースとかには使ってます。
PHPも対応してるみたいなので、、、どうでしょうか?


ちょっと確認: PHP向けのソースコードドキュメンテーションシステム


コメント

  • プログラムのドキュメンテーションはやらないとダメですよね。でも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 2005-03-07 (月) 15:51:07
  • PEAR ライブラリでは phpDocumentor を採用していますよね。こちらを採用するメリットは、サポートされる出力形式が多いこと、処理が高速なこと、あたりですが、実際みなさまどの程度採用されているかは良く知りません。私は phpDocumentor を使っています。phpDocumentor のページには「PHPDoc とも呼ばれている」と書いてありますが、通常 PHPDoc と呼ばれるものとは別ものだと思います……。 :p こちらを採用されてはいかがでしょうか。 -- kawai? 2005-03-08 (火) 02:16:39
  • ツッコミありがとうございます。双方の情報を上に追記しておきました。 -- henoheno 2005-03-08 (火) 22:06:51
    • okkezさんが試しているのもphpDocumentorの方みたいですね。 -- henoheno 2005-03-08 (火) 22:07:29
    • はい(その通りです。 -- okkez 2005-03-09 (水) 02:35:29
  • http://fullmetal.dip.jp/doc/ でちょこちょこコメント付けてドキュメント化してます。まだ途中ですが、無いよりマシなレベルにはなってきたと思います。手伝ってくれる人募集します。*1 -- okkez 2005-09-27 (火) 01:46:18
    • 美しいですねぇ~ :) -- teanan 2005-09-29 (木) 08:33:13
    • もちろん募集は自由です :) この中で一番の経験者は okkez さんなので、今までの経験を踏まえたポイントなど教えていただけると、検証する側として助かります :) コンセプトに沿ったコメントをさらに追加できるならば追加したいし、より効果的なドキュメントを生成できるいけてる工夫があればそれを検討したいです :) -- henoheno 2005-09-29 (木) 21:58:40
    • コメント付けのコンセプトは、
    1. プラグイン作者がどの関数を使えるのかわかるようにすること
    2. また、クラスや関数の使い方が簡単にわかるようになること
    3. これから開発に参加する人が、全てのソースコードを読まなくても概略がわかるようにすること

      ですね。

今、どうしようかと思っているのは、

  1. プラグインのパッケージ名*2
  2. 関数のアクセス権限*3
  3. クラス変数/インスタンス変数の役割

    です。 -- okkez 2005-09-30 (金) 21:40:43

  • この件に関して、okkezさんから、phpDocumentorのコメント入りのソースを受け取りました。今後teananさんと順次適用して行くと思います。 -- henoheno 2006-08-25 (金) 01:04:22
    • phpDocumentorは現在ではZendStudioとも連携するようになっています*4。今までのokkezさんの行動も考慮するに、phpDocumentorを採用するのが自然な流れでしょう。 -- henoheno 2006-08-25 (金) 01:05:58
    • 利点について。(1) 利用者にとって、PukiWikiソースの内部で定義されている関数を探しやすくなるかもしれない (2)少なくとも関数ヘッダーの様式が統一され、読み易くなるかもしれない -- henoheno 2006-09-02 (土) 16:09:28
    • 欠点について。導入当初、ソースの差分が膨大に発生するので、コードのチェックが大変になる。そのため、できればこの件に関する修正はリリース作業の終盤にまとめて行うのが理想です。しかし前に進めるためならそれ以外のタイミングでも問題ありません。 -- henoheno 2006-09-02 (土) 16:11:04


*1 勝手に募集してもいいですか?
*2 無いとドキュメント生成したときに見栄えがよろしくない
*3 publicなのかprivateなのか
*4 厳密には ZendStudio phpDocumentorと連携する

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2006-09-02 (土) 16:12:43
Site admin: PukiWiki Development Team

PukiWiki 1.5.2+ © 2001-2019 PukiWiki Development Team. Powered by PHP 5.6.40-0+deb8u7. HTML convert time: 0.291 sec.

OSDN