問題タブ [xml-documentation]

NDocやSandcastleなどのツールを使用して、.Netコードxmlドキュメントからドキュメントを生成できます。

だから私の質問：どうすれば簡単にページを追加できますか？

たとえば、ドキュメントのトップレベルに「語彙」または「概要」ページを追加したいと思います。

SandCastleのようなツールを使用すると、「NamespaceDoc」クラスを使用して名前空間のドキュメントを追加できることを知っています。これは素晴らしいですが、私が望む柔軟性を提供していません。

さらに、これらのページがxmlドキュメント（例：「詳細」）を介してリンク可能であると便利ですが、ページを挿入する基本的な方法すらわからないため、これは質問しすぎる可能性があります。

私は通常、クラス内のフィールドをプライベートフィールドとして宣言し、外部からこのフィールドにアクセスするパブリックプロパティを宣言しています（これまでのところ、目を見張るものはありません）：

同じコメントを 2 回書くことなく、この状況にコメントするエレガントで効率的な方法があるかどうか疑問に思っていました。言い換えれば、ツールチップでマウスをホバリングしているときに、IDE が変数のコメントを表示するという機能を保持したいと考えています。

これまでのところ、私はこのようにコメントしています：

そして、私はこのようなものが欲しいです:

生成されたドキュメントには表示されないため、プライベート フィールドのコメントに XML タグを使用してもあまり意味がないことはわかっていますが、(IDE 内部の) コメント ツールチップのみが必要です。

多分誰かが手がかりを持っています:)

アセンブリには、XML-DocとSandcastleを使用して文書化する必要のあるインターフェイスがいくつかあります。ただし、ドキュメントファイルを作成するときに無視したいインターフェイスもいくつかあります。今のところ、とマークされたインターフェイスを使用してアセンブリをコンパイルすることでそれを行うことができますinternalが、実際には、これらのインターフェイスが必要であるため、これは問題の解決策よりも回避策ですpublic。不要なものを無視して無視できるような属性はありますか？

メソッドの目的が値を計算して返すことである場合、私は次のように文書化しています。

ここで、returnsタグは新しい情報を提供しません: summary. (例外は を返すメソッドで、との戻り値の意味をbool簡単に説明できます。)truefalse

何か不足していますか？summaryとreturnsタグの間の繰り返しを避けるために XML ドキュメント ブロックを表現する標準的な方法はありますか?

重複の可能性:
C#: xml ドキュメントでジェネリック クラスとメソッドを参照する方法

1 つのパラメーターを持つ静的関数の短いドキュメント (VS2010) を作成したいと考えていIDictionary<TKey, TValue>ます。

例えば ​​：

VS2010 でドキュメントを作成したいのですが、/3 回入力すると、次のように自動的に生成されます。

このように書きたいと思います。key辞書は何かであり、辞書は別のvalueものです。

どうやってするか ？

私のプロジェクトを調べてドキュメントを展開しようとすると、次のような状況になります:

cref は次のエラーを生成します。

警告 C4638: XML ドキュメント コメントが 'Test.TypeOne.AAA' に適用されました: 不明なシンボル 'Test::TypeTwo' への参照。

TypeTwoを認識するためにxmlドキュメントを取得する方法はありますか? TypeTwo を TypeOne の上に置くだけですが、TypeTwo は TypeOne の cref としても使用されるため、同じ状況に戻ります。

私は愚かなだけですか？

Noda Timeには、出荷するXMLドキュメントファイルにすべての内部メンバーとプライベートメンバーも含まれているという問題があります。これは残念です。

幸い、Sandcastle Help File Builderには、カスタムビルドコンポーネントがあります---IntelliSenseComponent理論的には正確に正しいことを行います。残念ながら、私はそれを適切に構成する方法を地球上で理解することができません。

ドキュメントはこの例を示しています：

および状態：

上記の例は、Sandcastle HelpFileBuilderの構成ファイルから抜粋したものです。置換タグ{@SHFBFolder}および{@OutputFolder}を使用すると、ヘルプファイルビルダーのフォルダーとプロジェクトの出力フォルダーがファイルパスに挿入されます。これらは、ビルド時に適切な値に置き換えられます。独自のビルドスクリプトでコンポーネントを使用する場合は、タグをコンポーネントアセンブリと出力フォルダーへの相対パスまたは絶対パスにそれぞれ置き換えます。

ええと、私はSHFBを使用しているので、それが機能することを期待しています。しかし、私は絶対的な道以外のものを得ることができません。私はもう試した：

（検索しやすいものとしてXYZZYを使用しています。）

ソースコードを見て、環境変数を使用できることを望んでいましたが、これは機能しませんでした。

これはしましたが...

これは機能します：

...しかし、絶対パス名は必要ありません。

ドキュメントは、これらすべてが本当に簡単であるべきだと示唆しています...私は何が欠けていますか？

関連するバージョン：

• SHFB：1.9.3.0
• サンドキャッスル：2.6.10621.1

このアプリケーションの試用版をダウンロードしましたが、動作していないようです。クイック セットアップ ガイドを読みましたが、すべてが素晴らしかったです。任意のタイプのメンバーにカーソルを置いて Ctrl+Shift+D を押しても何も起こりません。上に置いたり、中に入れたり…何もありません。メンバーの上で Ctrl+Shift+A (2 回) を押すと、「フォーム MyType myVariable; の行に」配置するように指示されます。C# を参照していない限り、これが何を意味するのかよくわかりませんが、このプロジェクトは認識されていないように見える VB.NET です。他の誰かがこの問題を抱えていますか? メンバーごとに文書化するのではなく、文書全体を文書化できることを読んだので、物事が簡単になることを望んでいました。

VS 2010 プレミアムを使用しています。

クラスのXMLドキュメントにコードスニペットを含めようとしていますが、コンパイラがxml要素が閉じられていないと文句を言います。これが私が達成しようとしていることです

コードスニペットを次のように置き換えようとしました/// <c> MyClass class = new MyClass{String}(); </c>

誰もがこれを以前に経験したことがありますか？

ご協力いただきありがとうございます

興味深いものを持っています。C# で XML ドキュメント コメントを使用してメソッドをドキュメント化しています。ディレクティブを使用して、参照ファイルのすべてのコンテンツを含めたいと考えています。xml ドキュメントとしてフォーマットされた文字列を受け取るコードをドキュメント化しています。パラメータ ドキュメントに XSD ファイルを含めたいと考えています。

これは、Visual Studio によって生成された XML が期待どおりであるため、正常に機能します。XML のスニペットを次に示します。

ただし、Sandcastle を使用してこれからヘルプ ファイルを生成すると、xsd ファイルの内容は表示されませんが、Sandcastle はエラーを報告しません。私は、ヘルプファイルがある場所にも相対的なファイル名を使用しようとしました。

しかし、その後、Visual Studio はファイルが見つからないと不平を言います。それらを両方の場所に配置しましたが、含まれているファイルは表示されません。

何か案は？