問題タブ [xml-documentation]

今日、Sandcastle Help File Builder を起動して、ソリューションのドキュメントを生成しました。このソリューションには、約 12 個のプロジェクトが含まれています。ドキュメントを生成し、リリース ビルド (すべてのテスト プロジェクトを除外) の後に Sandcastle を実行したいだけなので、VS の場合と同様に、ウィンドウの上部で [リリース] を選択しました。Sandcastle は、各プロジェクトの \bin\release サブフォルダーで生成された XML ファイルを適切に探します。ただし、テスト プロジェクトの DLL が見つからない場合、エラーが発生します。ソリューション ファイルにこれらのプロジェクトが表示されているようですが、リリースにそれらのビルドがないことを認識していません。「API フィルター」プロパティでそれらの選択を解除しようとしましたが、何も変わりません。

Sandcastle にこれらのプロジェクトを無視させるにはどうすればよいですか?

ILMerge を使用して、いくつかの C# プロジェクト DLL をソリューション全体の 1 つの DLL にマージします。各プロジェクトで Intellisense 用のドキュメントの .XML ファイルを作成していますが、マージした DLL を別のソリューションで参照として使用しようとすると、これらのコメントが表示されません。これらのファイルはすべて同じディレクトリにあります。

• MergedProjectDlls.dll
• Project1.XML
• Project2.XML
• Project3.XML
• Project4.XML

単一のプロジェクト XML ファイルの名前を MergedProjectDlls.XML に変更してから、Visual Studio で参照を削除して再度追加しようとしましたが、Intellisense は、名前を変更したプロジェクト XML ファイルにあることがわかっているコメントをまだ認識していませんでした。

とにかく、これらすべてのプロジェクト XML ファイルを MergedProjectDlls.XML というタイトルのファイルにマージしたいと考えていました。それは可能ですか？それが MergedProjectDlls.dll と同じディレクトリにある場合、Intellisense はそれを自動的に取得しますか?

編集：MSDNでこれを見つけました：

生成された .xml ファイルを IntelliSense 機能で使用するには、.xml ファイルのファイル名をサポートするアセンブリと同じにし、.xml ファイルがアセンブリと同じディレクトリにあることを確認します。したがって、アセンブリが Visual Studio プロジェクトで参照されると、.xml ファイルも検出されます。

また:

/target:module でコンパイルしない限り、ファイルには、コンパイルの出力ファイルのアセンブリ マニフェストを含むファイルの名前を指定するタグが含まれます。」

xsd.exeを使用して、xsd ファイルのコレクションから C# クラスを生成しています。xsd ファイルは、<xsd:documentation>タグを使用して有用な説明を含めます。例：

残念ながら、生成された C# クラスでは、これらすべてが失われています。興味深いことに、各クラスには空のremarksドキュメント タグが関連付けられています。

このドキュメントを生成された C# クラス (またはドキュメント タグ) に含めるにはどうすればよいですか?

すべてのVS2008XMLドキュメントコメントファイルを1つの場所に保存し、このすべてのドキュメントのライブラリとして機能できるソフトウェア/アプリはありますか？

すべて相互接続された多くのWebプロジェクトを作成しており、VSによって作成されたすべてのXMLドキュメントを1か所に配置する必要があります。したがって、単一のソフトウェア/アプリを介してすべてのドキュメントと検索コードまたは参照にアクセスできる場所として機能する可能性があります。

そのXMLを確認すると、XSLTを作成してすべてのドキュメントを変換できますが、最初に、すでに実行されているものを探しています。カスタムアプリは私たちの2番目の選択肢です。

あなたの推薦をありがとう！

メソッドとクラスに関する .NET XML コメントでは、使用例を<example><code></code></example>ブロックで提供するようにしています。<code>Sandcastle を使用して、XML ドキュメントを使用して .chm ドキュメント ファイルを生成すると、常に適切にフォーマットされ、ブロック内の改行が尊重されます。ただし、Visual Studio のオブジェクト ブラウザーでクラスとメソッドを参照すると、すべてが 1 行でまとめて実行され、フォントはすべて同じです (コードのモノスペースはありません)。これは、XML コメントで私が何かをし損ねているためですか、それともオブジェクト ブラウザが単に馬鹿げているだけなのでしょうか? 私は特に Visual Studio 2008 Team System を使用しています。

Sandcastle ドキュメントと Intellisense の両方に使用する XML ファイルを生成する C++/CLI 混合モード アセンブリがあります。

アセンブリをスキャンしてすべてのエントリを作成するツールを使用していますが、残念ながらこのツールがどのように機能するかはわかりません。また、次のようなメソッド シグネチャを処理することもできません。

XML ファイルでは、このパラメーターが System.Int32!CompilerServices.IsLong@ であることが想定されていますが、ツールではそれを処理できません。

つまり、アセンブリをスキャンして、Intellisense に必要な XML ファイルを作成するにはどうすればよいでしょうか。

C# で Web Client Software Factory (WCSF) を使用して ASP.net Web アプリケーションで作業しているときに、このジレンマに遭遇しました。同じことが他のプラットフォームや言語にも当てはまる可能性があります。私の状況は次のとおりです。

WCSF パラダイムに基づいて各 Web ページ/ユーザー コントロールの I View インターフェイスを定義してから、ページ クラスに I View インターフェイスを実装させ、基本的にインターフェイスで定義された各メソッドを実装します。メソッド レベルで xml-documentation を追加しようとしたとき、基本的に、インターフェイス メソッドと実装クラスの対応する部分の両方に対して同じコメント コンテンツを繰り返していることに気付きました。

私の質問は次のとおりです。インターフェイス メソッドと対応するクラス メソッドのドキュメント コンテンツの間に実質的な違いがあるはずですか? 彼らは別の側面か何かを強調すべきですか？

インターフェイス メソッドのコメントにはメソッドが「何をするか」を記述し、クラス メソッドのコメントには「どのように」メソッドを実行するかを記述する必要があると誰かが私に言いました。しかし、メソッド レベルのコメントは、メソッドが実行することになっている "何" だけを記述すべきであり、メソッドの実装の詳細を記述すべきではないことを以前どこかで読んだことを覚えています。

一部のメソッドにxmlタグを追加しました<returns>が、IntelliSenseでそのコンテンツを表示できません。

これが私のコードです：

このコンテンツを表示する方法はありますか？

私は最近多くの VC++ 2008 / CLI ソフトウェアを作成しており、C#/CLI スタイルのドキュメントを使用しています。

私はこれらのブロックをかなり頻繁に再入力していることに気づきました。率直に言って、それは繰り返しになっています。新しい関数定義を作成したり、既存の定義を更新したりするときに、Visual Studio でこれらのブロックを自動的に作成/更新する方法はありますか?

列挙型フィールドのデフォルト値を文書化したい：

コンパイラは、参照を解決できなかったことを警告します。プレフィックスF：またはM：はコンパイラを無音にしますが、E：も無音にするので、どのプレフィックスが正しいかわかりません。