web-dev-qa-db-ja.com

ドキュメント用のDoxyGenを備えたVisual Studio、または他のものを使用する必要がありますか？

現在、DoxyGenを使用して、C/C++、PHP、およびJavaで記述されたコードを文書化します。

しかし、私たちは疑問に思っています：

  • DoxyGen以外のものを使用して、生成されたドキュメントのレイアウトまたは構造に利点がありますか？ C＃および.NETプラットフォームの経験がある外部開発者向けのドキュメントを生成しています。特定のドキュメント形式に慣れているのでしょうか？
  • DoxyGenはVisual Studioとどれだけうまく統合できますか？ IDE内からワンクリックでドキュメントを生成できるものはありますか？
  • 他のドキュメントシステムはVisual Studioとより統合されていますか？
c#visual-studiodocumentation
47
Deleted

Visual StudioでC＃コードをドキュメント化するデフォルトの方法は、 XMLドキュメントコメント です。私の意見では、これはVisual Studioに既にサポートされているため、これがC＃コードの最適な方法です（コメントタグの自動補完、パラメーターの欠落またはスペルの誤りに関する警告など）。メソッドを文書化するには、3つのスラッシュ（///）メソッド本体の前に、Visual Studioは次のように空のコメントテンプレートを挿入します。

/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
    // ...
}

すべてのコメントからXMLファイルを生成するようにVisual Studioを構成できます。これは、 Sandcastle などのドキュメントジェネレーターに入力されます。 Doxygen を使用する場合、XMLコメントの解析をサポートするため、これは問題ありません。

要約すると：C＃コードの特別なDoxygenコメントよりもXMLコメントを使用することをお勧めします。このように、すべてのオプションがあります。組織が使い慣れている標準のDoxygenレイアウトでドキュメントを生成できます（DoxygenがXMLコメントをサポートしているため）。また、.NET開発者に知られている形式でドキュメントを生成するオプションがあります（Sandcastleおよび Sandcastle Help FileBuilder =）。

ああ、また試してみてください GhostDoc ...

47
Christian

ドキュメントにはいくつかのオプションがあります。

  • 無料のマイクロソフトの方法。 DocXmlドキュメントコメントを使用してから、Sandcastleまたは同様のツールを使用して、MSDNスタイルのドキュメントを作成します。これの利点は、Visual Studioがドキュメントを認識し（コメントの構文に色を付ける）、ドキュメントがIntellisenseシステムによって即座に取得されることです（したがって、呼び出しているメソッドにマウスポインターを合わせると、ツールチップに文書コメントに入力した要約およびパラメーター情報）

  • 無料のDoxygenシステム。これは使いやすく柔軟性がありますが、Visual Studioではサポートされていないため、インテリセンスと構文の色付けの利点が失われます。プラス面として、DoxygenはDocXml形式を解析するため、DoxygenでDocXml形式を使用して外部ヘルプを生成することにより、両方の世界のベストを取得できます。

  • WYSIWYGウィンドウでドキュメントを編集できるDocumentXなどの商用製品。

DocXmlコメントとDoxygenから始めて外部ヘルプを生成することをお勧めします。これは最も安価で簡単に開始でき、VIsual Studioのすべての最高の機能（intellisenseなど）を保持しているためです。

また、アドイン Atomineer Pro Documentation を参照することをお勧めします。これにより、VS内でDocXml、Doxygen、Qt、またはJavaDoc形式のコメントの生成と更新がはるかに速く簡単になります。ドキシゲンとサンドキャッスルの両方に。

25
Jason Williams

DoxygenはC＃docコメント（///）を問題なく使用できます。通常どおりにコードを文書化し、doxygenを実行してスタンドアロンのhtml、chm、pdfファイルにスキャンします。これは、最も汎用性が高く、シンプルで非侵襲的なアプローチです。

DoxygenはVisual Studioに統合されていませんが、シンプルなIDEが付属しており、カスタム外部ツールとして簡単にスクリプト化できます。個人的に、doxygenをビルドスクリプトに統合しました。

最後に、doxygenはクロスプラットフォームで（これはMonoに移植する必要がある場合に有利です）、SandCastle（セットアップと実行の両方）よりも大幅に高速です。

これは〜1MlocプロジェクトのC＃コードのdoxygen出力の例です： http://www.opentk.com/files/doc/annotated.html

14
BlackStar

.NET開発者は、VSヘルプで使用されるMSDN形式のドキュメント形式に慣れています。 F1ヘルプ、フィルター、統合インデックス、TOCなどのボーナス機能を提供するため、VSヘルプに直接統合することが望ましいです。いくつかのツールについてはすでに言及しました。もう1つの商用ワンクリックソリューション VSdocman を追加します。

XML docコメントは、IntelliSenseおよびオブジェクトブラウザのクイック情報でも自動的に使用されるため、優れています。

1
Peter Macej

Visual Studioには、統合されたドキュメントシステムがありません。

他の言語との一貫性を保ちたい場合は、Visual Studioの Doxycomment AddinでDoxygenを使用してみてください。

C＃または.NETのドキュメントの場合、いくつかのツールが存在し、（私の知る限り）最も使用されるツールは Sandcastle です。

最後に、これを確認できます ブログエントリ これは、C＃固有のタグをDoxygenのタグに変換する小さなPythonスクリプトを提供します。

0
Laurent Etiemble