.NETでのXMLコードのコメント

Question

コードファイルでXMLコメントをどのくらい使っていますか？どのように使用しますか？ XML文書を生成するためにXML文書を使用できることがわかりましたが、このXML文書を使用してコードのHTMLヘルプファイルまたはスキーマファイルを生成できますか？

はまた、あなたは、任意の自動生成コメントツール（すなわちGhostDoc）を使用している、とあなたの印象は何ですか？

思考？

Answer 1

XMLドキュメントには便利です。このようにして、APIのすべてのコンシューマは、Intellisenseまたはオブジェクトブラウザを介してIDE内から利用可能な有用な情報を得ることができます。

おそらくXMLコメントの最大の利用は、これらのビルドされたXMLファイルからのヘルプドキュメントの生成です。 Microsoft Sandcastleはこれを現時点で検討する方法です。 HTMLヘルプ1（すなわちCHM）ファイルまたはHTMLヘルプ2（つまり、Visual Studioヘルプに統合できるヘルプファイル）を生成することができます。 （注：過去にNDocのオプションがより魅力的に思えるかもしれません - そして一部の人々はまだそれを使用しているかもしれませんが、サンドキャッスルは公式で推奨される方法です。目的）。開始するにはSandcastleDocsのWebサイトを参照してください（これは私が信じているMicrosoftの開発者の一人が非公式にまとめたものです）。特に、Sandcastle Help File BuilderのGUIをチェックしたいと思うでしょう - 私の経験上、私はそれが優れたツールであることがわかりました。

Answer 2

はい！私はそれらを使用しており、すべてのプロジェクトで私がそれらを含めることを要求しています。含まれるディテールのレベルは、コードの目的によって異なります。少なくとも、すべてのパラメータとパブリックメソッドに要約情報があります。複雑な項目には通常、コード例があり、特にスローされた例外はすべて文書化されています。

は、今私は、ドキュメントのビルドを行うにはサンドキャッスルを使用しています、あなたはまったく問題なくHTMLやCHMに行くことができます！私はまた、オンザフライ解析を行うSlickEditを使用しました。

Answer 3

はい、私はこの機能を使用し、すべての開発者がAPIにコメントすることをお勧めします。いくつかのapiのためにこれをやった後、そしてあなたがそれの上にとどまっている限り、それを維持することは本当に難しいことではありません。

オプション1：SandCastle これを使用しようとしましたが、実行してインストールして設定することが非常に多くのインストーラがあることがわかりました。結局、私はchmファイルで終わったが、実際には少し軽いものが欲しかった。

最終的な製品は非常にプロフェッショナルに見えます。私の状況ではうまくいかなかった。

オプション2：たNdoc 私がチェックした最後の時間、このプロジェクトは維持され、唯一の.NETのバージョン1.1で働いされていませんでした。

オプション3：XSLTはCodeProjectの上 誰かが、私はそれを試みたが、ここではそれがどのように動作するかだきました。この

http://www.codeproject.com/KB/XML/XMLDocStylesheet.aspx

ためのXSLTファイルを書いています。 プロジェクトをビルドし、出力されたxmlファイルと同じディレクトリにxsltファイルをドロップします。 xmlファイルをダブルクリックすると、xmlドキュメントの代わりに書式設定されたWebページが表示されます。

私にとっては、このオプションが最適でした。

Answer 4

少なくとも、パブリックAPIのコメントを入れてxmlファイルを生成します。それはインテリセンスの仕事をするのに十分であり、リフレクターにも現れます。

個人的には、私は砂浜などを気にしませんが、私はISVプロジェクトの可能性があります。

Answer 5

すべてのメソッドとプロパティをXMLコメントで記述します。どちらも内部の文書化の目的で、バイナリのヘルプファイルを提供できるようにするためです。 IntelliSenseでメソッドのポップアップを表示させることは特に便利です。

私たちはGhostDocを使用しています - それは多くの場合OKのデフォルト文書を提供できますが、GhostDocはメソッドとパラメータ名から推測できるものだけを文書化できることに留意してください。したがって、GhostDocを使用してドキュメントを開始することができます。それを適切に編集してください - 多くの場合、パラメータのデフォルトドキュメントはうまくいくでしょう。単純なケースでは、わかりやすい場合はデフォルトドキュメントを貼り付けるだけです。

Sandcastle(download)を使用してヘルプファイルを生成することができます。また、the Sandcastle Help File Builderは、Sandcastleを使い始めやすいGUIです。

Answer 6

私はそれが何をしているかがはっきりとわからないどんな方法でもしようとしています。私はそれがIntellisenseの文書を含んでいるのが好きです。

Answer 7

過去にMicrosoftのSandCastleツールを使用して、XmlコメントからMSDNスタイルのドキュメントを生成し、本当にうれしかったです。おそらくそれはXmlのコメントから来るすべての.netフレームワークドキュメントを生成するために使用されるツールです。あなたがのDLLと一緒にビルドからXMLファイルを配布する場合は、それ自体で

http://msdn.microsoft.com/en-us/vstudio/bb608422.aspx

Answer 8

NuDocを活用して、マークダウン形式の静的APIサイトを生成しています。 APIは、きれいでモダンで、非常に軽量で使いやすいです（自分で言うかもしれませんが）。）：http://kzu.to/nudoc

これもオープンソースなので、修正や改善が常に歓迎されています。