4

私の最初のオープン ソース プロジェクト (恥知らずなプラグイン: mtChart ) では、現在 2 種類のドキュメントがあります。

  • コード内の phpdoc-comments から Doxygen によって生成された HTML ファイル
  • Google Code の wiki ページ (または簡単に言えば、追加のテキスト ファイル)

Doxygen ファイルは非常に優れていますが、チュートリアル、例、システムの概要、ロードマップなどの「ハイレベル」ドキュメントを追加する可能性がありません。

これら 2 つを自動化された方法で組み合わせるにはどうすれば、残りのテキストを何らかの形で自動的に含めてコード ドキュメントを最新の状態に保つことができますか?

(必要に応じて、Doxygen から離れるつもりです。)

4

1 に答える 1

3

phpdoc-style を使用する場合は、例やチュートリアルなどをその中で実行し、必要に応じてロードマップなどの外部コンテンツへのリンクを提供できることを明らかに認識しています。理想的ではありませんが、確実に機能し、一貫性のある有用なドキュメントを提供します。コメント内でテキストを読みやすくするために書式設定を使用し、リンクを @see にするだけです。インライン タグの使用を検討することもできますが、最初からそこまでする必要があるかどうかはわかりません。

/**
 * @todo Need to move to the main framework
 *
 *        class: RegistrationPeer extends AbstractPeer
 *      package: Registration
 *   subpackage: Peer
 *
 *       method: findByUserId($userId)
 *   visibility: public
 *       static: yes
 *
 *         file: xxx
 *
 *        class: Registration extends AbstractModel
 *      package: Registration
 *   subpackage: Model
 *
 * Sample usage:
 * <code>
 * <?php
 *     $userId = $sessionManager->getRegUid();
 *     $registration = RegistrationPeer::findByUserId($userId);
 * ?>
 * </code>
 *
 * @see AbstractPeer
 * @see http://docs.google.com/Doc?docid=xxxx&hl=en
 *
 * @author xxx
 */
于 2009-08-26T09:42:25.500 に答える