.NET XMLドキュメント-ドキュメントの継承

StackOverflow https://stackoverflow.com/questions/311363

  •  10-07-2019
  •  | 
  •  

質問

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

役に立ちましたか？

解決

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

継承されているメソッド、またはインターフェイスメソッドをオーバーライドするためにドキュメントを完全に省略した場合はどうなりますか？ NDocの設定方法に依存するのではないかと思いますが、MSDNのドキュメントでは確かにドキュメントを自然に継承しているようです-クイックチェックは、プロテクションしない場合にVSがうごめかないことを示唆します継承されたメソッドのドキュメント。ぜひ試してみてください。

他のヒント

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

GhostDocでコメントを複製することは確かに有効なアプローチですが、次のような重大な欠点があります：

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

FiXmlの簡単な説明：C＃\ Visual Basic .Netによって生成されたXMLドキュメントのポストプロセッサです。 MSBuildタスクとして実装されているため、任意のプロジェクトに簡単に統合できます。これらの言語でのXMLドキュメントの作成に関連するいくつかの迷惑なケースに対処します。

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

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

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

ウェブページおよびダウンロードページ（リンク切れ）。

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

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

Sandcastleの<=>説明詳細については。

XMLドキュメントファイルを後処理して<！> lt; inheritdoc / <！> gt;のサポートを追加するコマンドラインツールを構築しました。タグ。

ソースコードではIntellisenseを使用できませんが、変更されたXMLドキュメントファイルをNuGetパッケージに含めることができるため、参照されるNuGetパッケージでIntellisenseを使用できます。

詳細については、 www.inheritdoc.io を参照してください（無料版が利用可能）。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top