guide - .NET xml ドキュメント継承ドキュメント



documentation ndoc (2)

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

継承されているメソッドやインターフェイスメソッドをオーバーライドするために、ドキュメントを完全に残しておくとどうなりますか? 私はあなたがNDocをどのように設定しているかによって異なりますが、確かにMSDNのドキュメントではドキュメントが自然に継承されているようですが、継承されたメソッドのドキュメントをprodiveしていないときにVSがうまくいきません。 おそらく試してみる価値がある。

NDocにはXML要素inheritdocがあり、親クラス(または実装されたインタフェース)からのメンバのドキュメントを継承することができます。 しかし、Visual Studio(つまりC#コンパイラ)はこのタグを理解していないため、ドキュメントが存在しないか、または完全ではないと不平を言っています。 StyleCopやその他のツールも同様です。 別の方法がありますか? XML記述を複製せずに、ドキュメントを完成させたままにするにはどうすればよいですか?


Answer #1

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

GhostDocでのコメントのクローン作成は確かに実用的なアプローチですが、次のような重大な欠点があります。

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

FiXmlの簡単な説明:C#\ Visual Basic .Netで作成されたXMLドキュメントのポストプロセッサです。 これはMSBuildタスクとして実装されているため、どのプロジェクトにも簡単に統合できます。 これらの言語でのXMLドキュメントの作成に関連する厄介なケースはほとんどありません。

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

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

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

ここにそのウェブページダウンロードページ (壊れたリンク)があります。

最後に、 Sandcastleに <inheritdoc>タグがあります。これはXMLコメントをコピーするよりも使用する方がはるかに優れていますが、FiXmlと比較していくつかの欠点があります。

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

詳細については、 Sandcastleの<inheritdoc>説明を参照してください。





ndoc