37

NDoc には、親クラス (または実装されたインターフェース) からメンバーのドキュメントを継承できるようにするXML 要素inheritdocがあります。ただし、Visual Studio (つまり、C# コンパイラ) はこのタグを理解せず、ドキュメントが存在しないか完全でないと文句を言います。StyleCop やその他のツールも同様です。代替アプローチはありますか？XML 記述を複製せずに、ドキュメントを完全な状態に保つにはどうすればよいでしょうか?

4

3 に答える 3

23

より良い答えがあります: FiXml。

GhostDoc を使用したコメントの複製は確かに機能するアプローチですが、次のような重大な欠点があります。

  • 元のコメントが変更された場合 (開発中に頻繁に発生します)、そのクローンは変更されません。
  • 大量の複製を作成しています。ソース コード分析ツール (Team City の Duplicate Finder など) を使用している場合は、主にコメントが検索されます。

FiXml の簡単な説明: C#\Visual Basic .Net によって生成される XML ドキュメントのポスト プロセッサです。MSBuild タスクとして実装されるため、どのプロジェクトにも簡単に統合できます。以下の言語で XML 文書を作成することに関連するいくつかの面倒なケースに対処します。

  • 基本クラスまたはインターフェイスからのドキュメントの継承はサポートされていません。つまり、オーバーライドされたメンバーのドキュメントはゼロから作成する必要がありますが、通常は少なくともその一部を継承することが非常に望ましいです。
  • 「この型はシングルトンです。その<see cref="Instance" />プロパティを使用して、その唯一のインスタンスを取得します。」や「クラスの新しいインスタンスを初期化します。」など、一般的に使用されるドキュメント テンプレートの挿入はサポートされていません<CurrentType>。</li>

上記の問題を解決するために、次の追加の XML タグが提供されています。

  • <inheritdoc />, <inherited />タグ
  • <see cref="..." copy="..." /><see/>タグの属性。

ここにその Web ページとダウンロード ページ(リンク切れ) があります。

最後に、Sandcastle<inheritdoc>にはタグがあります。XML コメントをコピーするよりもタグを使用する方が確実に優れていますが、FiXml と比較して不利な点はほとんどありません。

  • .xmlSandcastle は、コンパイルされた HTML ヘルプ ファイルを生成します。抽出された XML コメントを含むファイルは変更しません。ただし、これらのファイルは、Visual Studio .NET の .NET Reflector やクラス ブラウザー \ IntelliSense など、多くのツールで使用されます。したがって、Sandcastle のみを使用する場合、継承されたドキュメントは表示されません。
  • Sandcastle の実装はそれほど強力ではありません。たとえば、 は no <see ... copy="true" />です。

詳細については、サンドキャッスルの<inheritdoc>説明を参照してください。

于 2009-07-03T18:33:10.403 に答える
14

別の方法の 1 つは、GhostDoc を使用することです。GhostDocは、コメントを自動的に生成する Visual Studio 用のアドインです。もちろん、これは回避しようとしているものの一部である XML 記述を複製しますが、少なくとも自動的にそれを行います。

継承されているメソッドやインターフェイス メソッドをオーバーライドしているメソッドのドキュメントを完全に省略した場合はどうなりますか? NDocの構成方法に依存すると思われますが、確かにMSDNのドキュメントでは、ドキュメントを自然に継承しているようです-簡単なチェックでは、継承されたメソッドのドキュメントを作成しないと、VSは泣き言を言わないことが示唆されています. 確かに試してみる価値があります。

于 2008-11-22T20:08:36.497 に答える