問題タブ [xml-comments]

Visual Studio XML出力からMSDNスタイルのドキュメントを作成する簡単な方法はありますか？
私はこの橋を渡る最初の人ではないことを知っているので、私はそれのために良いxsltを設定するのに十分な忍耐力がありません。

また、最近サンドキャッスルを設置してみましたが、本当に目が離せませんでした。その過程で重要な何かが欠けていたか、それはあまりにも複雑すぎます。

私はそこにいる誰かが本当に素晴らしい非常に単純な解決策を持っていることを知っています。

私のフォーマットによってその段落が読みたくないものになったと思うので、ここで繰り返します。

サンドキャッスルを試してみましたが、セットアップするのに本当に苦労しました。私が本当に心に留めているのは、もっと単純なことです。

つまり、砂の城のプロセスを理解していない限りです。テスターが作業するのに良いものを作るためだけに、私には非常に多くの余分な荷物のように見えました。

Visual Studio の LINQ to SQL デザイナーを使用して、データベースのオブジェクト モデルを作成しました。ここで、生成された各プロパティに XML コメントを追加したいと考えていますが、次回 dbml ファイルが更新されたときにプロパティを消去せずにそれを行う方法がわかりません。

これはどのように行うことができますか？

xml-comments を再フォーマットする VS 2008 用のマクロまたはアドオンを知っている人はいますか? 以前のバージョンの VS には非常にスマートな CommentReflower がありましたが、VS 2008 をサポートするリリースは見つかりませんでした。

何か案は？前もって感謝します！

マティアス

私はxmlドキュメントを使用したVS2008ソリューションを持っており、リリースモードでエラーがオンになっているため警告があります(私見の素晴らしい機能)。ただし、これにより、(自己記述型の) 列挙型のすべての要素などの「xml コメントがありません」エラーの長いリストが作成されます。

xml コメントの要件をオフにする属性などを知っている人はいますか? 理想的には、1行だけでなく、区切られた領域に（そうでなければ、すべてのアイテムの前に空のタグを付けて、目的を無効にすることができます...）

ありがとう！

全体またはC＃ソースコードには、次のような実際のコンテンツを見逃しているコメントがたくさんあります。

またはこれ：

またはこれ：

残念ながら、Visual Studioは、このタイプの欠落したコメントに対して警告を生成しません。しかし、私たちにとっては、Visual Studio内のリスト（警告リストなど）内のアイテムをクリックして、ソースコード内の誤った場所に移動して修正できれば便利です。また、xmlファイルのビルドごとに欠落しているxmlコメントコンテンツのリストを確認すると便利です。これを達成する方法について何か考えがありますか？

最近、慎重に作成した xml コメントが同僚の IntelliSense に表示されないことに少し驚きました。関連するアセンブリを常にプロジェクト参照に使用していたので、この情報にアクセスするには .xml ドキュメントもエクスポートする必要があることに気付きませんでした。

これにより、.Net フレームワークの IntelliSense がどのように機能するのか疑問に思いました。私の理解が正しければ、.xml ファイルは特別なフォルダーのどこかに隠されている必要がありますか?

しかし、私の主な質問は「Goto definition」に関するものです。.Net フレームワーク アセンブリの定義に移動すると、メタデータから生成された情報が得られますが、役立つコメントもたくさんあります。これらは Xml コメントから魔法のように生成されたものですか、それとも誰かビルドのためだけにそれらを変換するには、マクロを作成しますか? 別の言い方をすれば、アセンブリに対してこの効果を得るにはどうすればよいですか?

これは、.NET Framework BCLのクラスに関する多くのXMLコメントで見られましたが、その機能を説明するドキュメントを見つけることができませんでした。

例として、System.Objectを見ると、次のコメントが表示されます。

.NET ソース内のコード ドキュメントの量が多すぎますか?

いくつかの背景: SO に投稿した他の質問のいくつかで話した大きなコードベースを継承しました。このコードベースの「機能」の 1 つは、God クラスです。これは、数十の静的メソッドを含む 3000 行を超えるコードを持つ単一の静的クラスです。Utilities.CalculateFYBasedOnMonth()からまでのすべてUtilities.GetSharePointUserInfo()ですUtilities.IsUserIE6()。適切なライブラリ セットにリファクタリングするだけで、書き換える必要のない優れたコードです。私はそれを計画しています。

これらのメソッドは新しいビジネス レイヤーに移行しており、このプロジェクトでの私の役割は、他の開発者がシステムを保守できるように準備することなので、しっかりしたコード ドキュメントについて考えています。これらのメソッドにはすべて適切なインライン コメントがありますが、XML コメント形式の適切な (またはまったく) コード doco がすべて含まれているわけではありません。GhostDoc と Sandcastle (または Document X) の組み合わせを使用して、非常に優れた HTML ドキュメントを作成し、それを SharePoint に投稿できます。これにより、開発者は、コード自体をナビゲートしなくても、コードが何をするかをより理解できるようになります。

コード内のドキュメントの量が増えると、コードをナビゲートするのが難しくなります。//commentXML コメントを使用すると、たとえば、各メソッドを単純にするよりも、コードの保守が難しくなるのではないかと考え始めています。

これらの例は、ドキュメント X サンプルからのものです。

と：

だから私はあなたから疑問に思っていました: NDoc (RIP) や Sandcastle のようなものを使用することを目標に、すべてのコードを XML コメントで文書化していますか? そうでない場合、ドキュメントを取得するものと取得しないものをどのように決定しますか? API のようなものには明らかに doco がありますが、別のチームに引き渡して維持するコードベースについてはどうでしょうか?

私は何をすべきだと思いますか？

私は以前に数回この状況に遭遇しました。XML コメントで型を参照したいのですが、プロジェクトで参照されていないアセンブリにその型が含まれています。

A.Dll (B.DLL を参照) の場合:

B.DLL (A.DLL を参照しない):

LoserClassI need to referenceのコメントではSomeClass、B.DLL が A.DLL (循環参照) を参照していないため参照できません。

XML ドキュメント ジェネレーターで解決できるようLoserClassに、' コード ドキュメント内の cref にアセンブリ情報を含める方法はありますか?A.SomeClass

(ちなみに、他の場所で循環依存が発生する可能性があるため、クラスを移動することで常にこれを解決できるとは限りません)

おはよう、午後、夕方、または夜 (タイムゾーンによって異なります)。

これは、C# 内の XML コメントに関する一般的な質問です。私は自分のプログラムにコメントすることにあまり熱心ではありませんでした。私は常に、より詳細な変数/プロパティ/メソッドの命名者であり、コード自体に語らせてきました。かなり紛らわしいものをコーディングしている場合はコメントを書きますが、ほとんどの場合、多くのコメントは書きません。

.NET、Sandcastle、および codeplex のヘルプ ファイル ビルダーの XML コメントについて読んでいたところ、自分のコードを文書化し、自分のコードを掘り下げなければならない人のために素敵で役立つドキュメントを生成したいと思うようになりました。私がもうここにいないときのコード。

私の質問は、標準と慣習についてです。「良い」XML コメントのガイドはありますか? すべての変数とプロパティにコメントする必要がありますか? すべての方法？私は基本的に、サンドキャッスルによって適切なドキュメントにコンパイルされる優れたコメントを書く方法に関するヒントを探しているだけなので、他のプログラマーが私のコードで作業する必要があるときに私の名前を呪うことはありません。

あなたのアドバイスと提案を事前にありがとう、Scott Vercuski