74

職場にドキュメント生成ソリューションを実装する必要があり、タイトルに記載されている 3 つに絞り込みました。これらのソリューションを正式に比較する方法で、私はほとんど情報を見つけることができませんでした。上記の 1 つまたは複数の経験をお持ちの方が参考になることを願っています。

これが、最初のパスから収集できたものです。

HeaderDoc 長所: Apple の既存のドキュメントと一貫性があり、Apple Docsets の作成と互換性が
ある）。


Doxygenの長所: 幅広い使用ベースの活発なサポート コミュニティ b/c、非常にカスタマイズ可能、ほとんどの出力タイプ (latex など)

AppleDoc 長所: Apple の既存のドキュメントと一貫性があるように見える、Apple Docset の作成との互換性がある、
AppleDoc 短所: typedef、enum、関数のドキュメントに問題があり、活発に開発されている

これは正確に聞こえますか？望ましいソリューションには次のものがあります。

  • apples Objective-C クラス リファレンスとの一貫したルック アンド フィール
  • オプションを押しながらクリックして Xcode 内からドキュメント リファレンスを取得し、ドキュメントにリンクする機能 (Apple のクラスと同様)
  • カテゴリ、拡張機能などのスマートな処理 (Apple のクラスのカスタム カテゴリも)
  • 独自の参照ページを作成する機能 (このページのように: Loading... には、画像を含めることができ、生成されたクラス参照からシームレスにリンクできます。たとえば、Apple の UIViewController クラス参照がリンクされたページにリンクする方法のように.
  • ビルド スクリプトに統合できる、実行しやすいコマンド ライン コマンド
  • 非常に大きなコードベースの適切な処理

上記のすべての情報に基づいて、上記のソリューションのいずれかが他のソリューションよりも明らかに優れていますか? 追加する提案や情報は非常に高く評価されます。

4

3 に答える 3

90

doxygen の作成者および主任開発者として、私の視点も提供させてください
(明らかに偏見もあります ;-)

Apple 独自のドキュメンテーション スタイルの 100% 忠実なレプリカを探している場合は、その点で AppleDoc を選択することをお勧めします。doxygen を使用すると、まったく同じ外観を得るのに苦労するので、試すことはお勧めしません。

Xcode docsets に関して。Apple は、doxygen を使用してそれをセットアップする方法を提供しています (Xcode 3 がリリースされた時点で書かれています) 。Xcode 4 には、doxygen を統合するための優れたガイドもあります。

バージョン 1.8.0 の時点で、doxygen はMarkdown マークアップと多数の追加のマークアップコマンドをサポートしています。

doxygen を使用すると、メイン ページ (@mainpage) とサブページ (@subpage または @page を使用) にドキュメントを含めることができます。ページ内にセクションとサブセクションを作成できます。実際、doxygen のユーザーマニュアルは完全に doxygen を使用して書かれています。それに加えて、クラスまたは関数を一緒にグループ化し (@defgroup と @ingroup を使用)、クラス内でカスタム セクションを作成できます (@name を使用)。

Doxygen は設定ファイルを入力として使用します。テンプレートをデフォルト値で生成するdoxygen -gか、グラフィカル エディタを使用してテンプレートを作成および編集できます。また、スクリプトを使用して doxygen を介してオプションをパイプすることもできます(例については、 FAQdoxygen -の質問 17 を参照してください)。

Doxygen は Objective-C に限定されず、C、C++、Java を含む幅広い言語をサポートしています。Doxygen は Mac プラットフォームに限定されません。たとえば、Windows や Linux でも動作します。Doxygen の出力は、HTML 以外のものもサポートしています。PDF 出力 (LaTeX 経由) または RTF と man ページを生成できます。

Doxygen は純粋なドキュメントを超えています。doxygen は、ソース コードからさまざまなグラフや図を作成できます (ドット関連のオプションを参照してください)。Doxygen は、コードのブラウズ可能なシンタックス ハイライト バージョンを作成し、それをドキュメントと相互参照することもできます (ソース ブラウザ関連のオプションを参照してください)。

Doxygen は小規模から中規模のプロジェクトでは非常に高速です (ダイアグラムの生成は遅くなる可能性がありますが、最近では複数の CPU コアで並列に実行され、1 回の実行で得られたグラフは次の実行で再利用されます)。非常に大規模なプロジェクト (数百万行のコードなど) の場合、doxygen を使用すると、プロジェクトを複数の部分に分割し、ここで説明したようにそれらの部分をリンクすることができます。

Objective-C に doxygen を使用する実際の例は、こちらにあります。

doxygen の開発は、ユーザーからのフィードバックに大きく依存しています。質問と議論のためのアクティブなメーリング リストと、バグと機能要求の両方のためのバグ トラッカーがあります。

doxygen のほとんどのユーザーは C および C++ コードに使用しているため、これらの言語は当然、最も成熟したサポートを備えており、出力はこれらの言語の機能とニーズに合わせて調整されています。とはいえ、他の言語への要望や問題も真剣に受け止められています。

私はほぼすべての doxygen 開発と、Mac でのほとんどのテストを自分で行っていることに注意してください。

于 2012-04-12T18:41:15.357 に答える
83

私はappledocの作成者なので、この回答は偏っている可能性があります:)言及されたすべてのジェネレーター（およびその他）を試しましたが、望んでいた結果が得られなかったのでイライラしました（あなたと同様の目標）。

あなたのポイントによると（私はappledocとdoxygenについてのみ言及していますが、headerdocはあまり覚えていません）：

  1. 一貫した外観: すぐに使える appledoc、その他は css を微調整する必要がありますが、おそらく実行可能です。

  2. ドキュメント セットの生成 (Xcode 参照用): Appledoc は、すぐに検索可能でオプション クリック可能なドキュメントを完全にサポートします。doxygen は、自分で呼び出す必要がある xml と makefile を生成します。さらに、appledoc は公開されたドキュメントセットをすぐにサポートします。

  3. カテゴリ: appledoc を使用すると、カテゴリを既知のクラスにマージするか、別々のままにしておくことができます。基礎およびその他の Apple クラスのカテゴリは、インデックス ファイルに個別にリストされます。doxygen: 私が試したとき、これはうまく機能しませんでした。

  4. カスタム リファレンス ページ: appledocは、マークダウンまたはカスタム html のいずれかを使用してすぐに使用できるようにサポートしています。

  5. 簡単なコマンド ライン: 見方によって異なります。appledoc は、コマンド ライン スイッチを介してすべての引数を受け取ることができます (ただし、オプションのグローバルおよびプロジェクト設定 plist ファイルもサポートします)。そのため、ビルド スクリプトとの統合は非常に簡単です。doxygen では、すべてのパラメーターをセットアップするために構成ファイルを使用する必要があります。

  6. 大規模なコードベース: すべてのツールがこれをサポートする必要がありますが、時間的な比較はしていません。また、ツールがキャッシュされた値をサポートしているかどうかもわかりません (時間を節約するために、以前に収集したデータを実行しています)。次のメジャー リリースでこれを追加することを検討しています。

他のツールを試してからしばらく経っているので、上記の doxygen/headerdoc の問題は解決されている可能性があります。appledoc自体にも欠点があります：あなたが言及したように、列挙型、構造体、関数などのサポートはありません（この方向でいくつかの作業が行われました、この fork を確認してください）、それには、使用を妨げる可能性のある独自の問題があります。あなたの要件。

私は現在、列挙型、構造体などのサポートを含む、ほとんどの明白な問題をカバーするメジャー アップデートに取り組んでいます。大きなチャンクを完成させて十分に安定させるとすぐに、定期的に新しいものを実験的なブランチにプッシュしています。進捗。しかし、それはまだ非常に早い段階であり、進行状況は私の時間に依存するため、解決策が機能するまでにはかなりの時間がかかる場合があります.

于 2012-04-12T12:32:42.737 に答える
12

Xcode 5 は、コメントを解析してドキュメントを検索し、表示します。

コメントの例

もう appledoc や doxygen を使う必要はありません (少なくともドキュメントをエクスポートしたくない場合)。詳細はこちら

于 2013-09-19T16:05:12.750 に答える