7

XML Documentation Commentsを使用してアセンブリを文書化しています。そこからSandcastleを使用してchmファイルが作成されます。

私のアセンブリにはさまざまなインターフェイスが含まれており、それぞれが 1 つのクラスによって実装されています (私のシナリオでは、これらは WCF サービスです)。

インターフェイスにドキュメントを追加しました。実装クラスの関連メソッドを自動的にドキュメント化する方法はありますか?

4

4 に答える 4

3

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

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

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

前述のとおり、Sandcastle<inheritdoc>にはタグがありますが、FiXml と比較して不利な点はほとんどありません。

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

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

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

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

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

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

ここにその Web ページとダウンロード ページがあります。

于 2009-07-03T18:39:07.930 に答える
1

A tool such as GhostDoc can generate the documentation on the implementing classes, when you use it's keyboard shortcut. That is not entirely automatic, but could help prevent too much copy pasting.

Perhaps it could be automized with a script.

于 2009-04-15T09:12:52.197 に答える
1

AtomineerUtils はコメントを自動生成し、オーバーロードとオーバーライドされた基本クラスから既存のドキュメントを取得するため、必要な場所に情報を複製する手間が省けます。

http://www.atomineer.com/AtomineerUtils.html

于 2009-04-28T22:00:39.403 に答える