問題タブ [xml-documentation]

私はメソッドなどを文書化するためにGhostDocを使用しています...そしてうまく機能していますが、それは<returns>...

誰か私が何をすべきか教えてもらえますか

「ロール」というオブジェクトが返された場合

または単に

また

私はその音が少し正確すぎることを知っていますが、私は正しいことから始めたいです:-)

たとえば、ユーザー名の標準の文字列戻り値の型を考えてみましょう

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

私は see cref タグを使用しており、うまく機能しますが、see cref に string[] の一般的なリストを含める必要がありますが、ドキュメントが正しくレンダリングされません。

< と > とおそらく [] と関係があると思います

これは許可されていますか?回避策はありますか?

現在のアーキテクチャは、DB から DTO オブジェクトを設定して返す WCF サービスに基づいています。

一部のメソッドは完全なオブジェクト グラフを返しますが、一部のメソッドは部分的なグラフのみを返します。完全に移入された場合、一部のオブジェクト グラフは非常に大きくなります。そのため、すべてのケースに対応できるわけではありません。

多くのDTOオブジェクトのプロパティのうち、どのプロパティが入力され、どのプロパティが入力されていないかを文書化する方法は? これは .NET ショップであり、XML コメントは、常に入力されるとは限らないプロパティを文書化するのに十分な柔軟性を提供しません。他の人はこの課題にどのように取り組んでいますか?

例: クライアントにとって、Invoice オブジェクトは、すべてのプロパティが入力されているかどうかに関係なく同じです。

提案されている 1 つのアイデアは、入力されたプロパティのみを使用してオブジェクトの XSD スキーマを生成することです。技術的には正しいですが、これは「良い/使える」ドキュメントのようには見えません。

編集:UMLの方が読みやすいため、XSDよりも優れた代替手段である可能性があることがわかりました。XML -> XSD -> UML (または別の作図パラダイム) に簡単に移行する方法はありますか?

要約とパラメータのテキストを書くために、どのくらい詳細に入る必要があるか、完全な文を使用するかどうか、または何かについてのベスト プラクティスはありますか? これらをもっと使い始めると、確立するためのいくつかの良い習慣を探しています. ありがとう！

私はこの機能を持っています:

私が文書化したいもの。C# コードを読むことができる人なら誰でも、これは 1000 語以上を意味するので、タグに言って
もらいたいのです。しかし、私が使用するとき<return>string.Join(separator, strings.ToArray())

string.Join(separator, strings.ToArray()) はプレーンテキストとしてフォーマットされるため、ほとんど判読できなくなります。だから私は試しました

しかし、これは常に新しい段落を作成します...

では、私の質問は次のとおり
です。テキストの一部をフォーマットして、コードのように見せる方法はありますか? 等幅フォントで十分です。

私は.NETのXMLドキュメントの大ファンです。

ただし、正直に言うと、たとえば次のようなマークアップがあったチュートリアルやプロジェクトは見たことがありません。

それ以外の：

これには特別な理由がありますか？コントローラのメソッドを文書化したいのは私だけですか？

編集1：

ほとんどのコントローラーメソッドは単純なように見えますが、次の質問で詳しく説明されているケースはどうでしょうか。MVC：多くの子エンティティを持つエンティティを操作する方法は？？

私は VS 2005 の下で C# でクラス ライブラリを作成しています (私は知っていますが、現代ではわかりますが、ここでは予算が限られています)。

XML ドキュメントで「概要」タグを使用すると、ユーザーは Intellisense やツールチップなどを介してその情報を確認できますが、Studio の [プロパティ] ウィンドウでは確認できないようです。

そのウィンドウで何かを取得するには、[Description("This is it")]属性を使用する必要があるようです。

私はこれで正しいですか？もしそうなら、説明情報を複製する必要があるようです:-(

または、より良い方法はありますか？ありがとう！

インライン XML ドキュメント (つまり、3 つのスラッシュを使用する - ///) が機能しない理由は理解できたと思いますが、「問題」を回避する方法についていくつかのガイダンスを得たいと思います。

インターフェイスと 2 つの派生クラスがあります。派生クラスの 1 つはシミュレーション用で、もう 1 つは実際のハードウェアとの通信用です。

シミュレーターが行う必要のない特別なことをハードウェア実装が行う可能性が非常に高いです。シミュレーター用ではなく、ハードウェア メソッド用の XML ドキュメントがあります。ただし、メソッド名にカーソルを合わせると、ツールチップにドキュメントがまったく表示されません。これは、おそらく XML ドキュメントがインターフェイスに関連付けられていないためです。

これは確かに理にかなっており、代わりにドキュメントをインターフェイスに配置して、それと一緒に暮らす予定です。私はまだ興味がありますが、他の人はどのようにこれを行うのですか? ツールチップにすべての有効な XML ドキュメントを集約させる魔法のような方法はありますか? つまり、コンパイラはどの派生クラスが使用されているかを認識していないため、このインターフェイスを実装するすべてのクラスの XML ドキュメントを表示する方法はありますか?

XML ドキュメントを基本クラスから派生物に、またはインターフェイスから実装に伝達する必要があります。

Resharper を使用してこれを行うことはできますか?

「///」と入力すると、VS2010 は xml-doc ブロックを挿入します。ただし、挿入される xml-doc テンプレートをカスタマイズする方法はないようです。VB.NET または GhostDoc などの外部ツールを使用する方法しか見つかりませんでした。

外部ツールなしでそれを行う方法はありますか?