Objective-Cのドキュメントジェネレータ。HeaderDocとDoxygenとAppleDocの比較

質問

私の職場にドキュメント生成ソリューションを導入する必要があり、タイトルにある 3 つに絞り込んでいます。これらのソリューション間の正式な比較という点では、ほとんど情報を見つけることができなかったので、上記のうちの 1 つ以上の経験をお持ちの方にご意見を伺えればと思います。

以下は、私が最初のパスから得たものです。

HeaderDoc の長所。Apple の既存のドキュメントとの一貫性、Apple のドキュメントを作成する際の互換性

HeaderDoc の短所: 動作の修正が難しい、プロジェクトが活発に行われていない、多くの人が切り替えている (つまり、数値化できないが、何か欠陥があるはず)。

Doxygen 長所。 広範な使用ベースがあるためアクティブなサポートコミュニティがある、非常にカスタマイズしやすい、ほとんどの出力タイプ (latex など) がある。

Doxygenの短所 Apple のドキュメントとの互換性は、それほど単純ではありません。

AppleDoc 長所。 AppleDoc Pros: Appleの既存のドキュメントと見た目が一致し、Appleドキュメントセットとの互換性がある。

AppleDocの短所。 型定義、列挙型、関数のドキュメントに問題がある。

これは正確に聞こえますか？私たちが望む解決策は

• りんごの objective-c クラスの参照と一貫したルック アンド フィール。
• オプションクリックで Xcode 内からドキュメントリファレンスを引き出し、ドキュメントにリンクする機能 (アップルのクラスと同様)
• カテゴリ、拡張機能などのスマートな処理 (アップル社のクラスのカスタム カテゴリも)
• 独自の参照ページを作成する機能 (このページのような。Loading...のように、画像を含むことができ、apple の UIViewController クラス参照がリンク先ページにリンクするように、生成されたクラス参照からシームレスにリンク可能なページを作成できる。
• ビルドスクリプトに統合可能なコマンドラインコマンドを簡単に実行できる。
• 非常に大きなコードベースの優雅な処理

上記のすべての情報に基づいて、上記のソリューションのうちどれかが他よりも明らかに優れているのでしょうか？何か提案や追加すべき情報があれば、非常に感謝します。

どのように解決するのですか？

doxygenの生みの親であり、リード開発者として、私の見解も述べさせてください。

(明らかに偏見もありますが;-)

もしあなたがApple自身のドキュメントスタイルを100%忠実に再現したいのであれば、その点ではAppleDocの方が良い選択でしょう。doxygenでは、全く同じ外観を得るのは難しいでしょうから、試すのはお勧めしません。

Xcodeのdocsetsに関しては、Appleが提供している 指示 を提供しています (Xcode 3 がリリースされたときに書かれたものです)。また、Xcode 4では 素敵なガイド があります。

バージョン1.8.0以降、doxyは以下のものをサポートしています。 Markdownマークアップ をサポートし、さらに多くの追加的な マークアップ コマンドを追加しました。

doxygenでは、メインページ（@mainpage）だけでなく、サブページ（@subpageまたは@pageを使用）にもドキュメントを含めることができます。ページ内では、セクションやサブセクションを作成することができます。実際、doxygenのユーザーマニュアルは完全にdoxygenを使って書かれています。そのほか、クラスや関数をグループ化したり（@defgroupや@ingroupを使用）、クラスの中に独自のセクションを作成することもできます（@nameを使用）。

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

DoxygenはObjective-Cに限らず、C、C++、Javaなど様々な言語をサポートしています。また、DoxygenはMacに限らず、WindowsやLinuxでも動作します。Doxygenの出力はHTMLだけでなく、PDF出力（LaTeX経由）、RTFやmanページも生成できます。

また、doxygenは純粋なドキュメントにとどまらず、ソースコードから様々なグラフや図を作成することができます( ドット 関連オプション参照)。また、Doxygenはあなたのコードのブラウズ可能なシンタックスハイライト版を作成し、それをドキュメントと相互参照することができます( ソース・ブラウザー 関連オプションを参照)。

Doxygenは小規模から中規模のプロジェクトでは非常に高速です（ただし、図の生成は遅くなることがありますが、最近では複数のCPUコアで並行して実行され、1回の実行で得られたグラフは次の実行で再利用されます）。 非常に大規模なプロジェクト（例えば数百万行のコード）では、doxygenはプロジェクトを複数のパートに分割し、私が説明したようにパートを互いにリンクさせることができます。 ここで .

Objective-Cでdoxyを使用した実例があります。 ここで .

doxygenの開発は、ユーザーからのフィードバックに大きく依存しています。私たちは積極的に メーリングリスト があり、質問や議論のために バグトラッカー を設置し、バグと機能要求の両方に対応しています。

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

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