問題タブ [ndoc]

私はD2007を使用しており、HelpInsight機能（D2005以降に提供）を使用してソースコードを文書化しようとしています。私は主にHelpInsightツールのヒントを機能させることに興味があります。さまざまなWebサーフィンと実験から、私は次のことを発見しました。

1. トリプルスラッシュ（///）コメントスタイルの使用は、他の文書化されたコメントスタイルよりも頻繁に機能します。すなわち： {*! comment *}そして{! comment }
2. コメントは、その目的の宣言の前に置く必要があります。ほとんどの場合、これはコードのインターフェースセクションにそれらを配置することを意味します。（明らかな例外は、現在のユニットの外部からアクセスできないため、実装ブロックで宣言されているタイプと関数の場合です。）
3. 最初のコメントは関数に対するものにすることはできません。（つまり、タイプ用である必要があります。または、少なくとも、HelpInsight機能が機能する前にパーサーが「type」キーワードを認識している必要があるようです）

これらの「ルール」に従っているにもかかわらず、Help-insightが私が書いたコメントを見つけられないことがあります。1つのファイルで正しいHelpInsightツールのヒントが生成されませんが、このファイルを別のダミープロジェクトに含めると、正しく機能します。

HelpInsightを機能させるためのその他の指針/コツはありますか？

.NET ソース内のコード ドキュメントの量が多すぎますか?

いくつかの背景: SO に投稿した他の質問のいくつかで話した大きなコードベースを継承しました。このコードベースの「機能」の 1 つは、God クラスです。これは、数十の静的メソッドを含む 3000 行を超えるコードを持つ単一の静的クラスです。Utilities.CalculateFYBasedOnMonth()からまでのすべてUtilities.GetSharePointUserInfo()ですUtilities.IsUserIE6()。適切なライブラリ セットにリファクタリングするだけで、書き換える必要のない優れたコードです。私はそれを計画しています。

これらのメソッドは新しいビジネス レイヤーに移行しており、このプロジェクトでの私の役割は、他の開発者がシステムを保守できるように準備することなので、しっかりしたコード ドキュメントについて考えています。これらのメソッドにはすべて適切なインライン コメントがありますが、XML コメント形式の適切な (またはまったく) コード doco がすべて含まれているわけではありません。GhostDoc と Sandcastle (または Document X) の組み合わせを使用して、非常に優れた HTML ドキュメントを作成し、それを SharePoint に投稿できます。これにより、開発者は、コード自体をナビゲートしなくても、コードが何をするかをより理解できるようになります。

コード内のドキュメントの量が増えると、コードをナビゲートするのが難しくなります。//commentXML コメントを使用すると、たとえば、各メソッドを単純にするよりも、コードの保守が難しくなるのではないかと考え始めています。

これらの例は、ドキュメント X サンプルからのものです。

と：

だから私はあなたから疑問に思っていました: NDoc (RIP) や Sandcastle のようなものを使用することを目標に、すべてのコードを XML コメントで文書化していますか? そうでない場合、ドキュメントを取得するものと取得しないものをどのように決定しますか? API のようなものには明らかに doco がありますが、別のチームに引き渡して維持するコードベースについてはどうでしょうか?

私は何をすべきだと思いますか？

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

NDoc Enhanced（ http://sourceforge.net/projects/ndoc-e/ ）のカスタマイズされたビルド（つまり、わずかにバグが修正されたビルド）を使用して、かなり長い間NDocを使用しましたが、奇妙な問題が発生しました。それ自体が一般的なパラメータをとるパラメータを持つメソッドを使用します。

たとえば、ディクショナリの型パラメータが基本クラス型ではないパラメータとしてディクショナリを含むものは、コードがType.FullNameを使用して型を取得する場合のように、ドキュメントを適切に検索できません。次のような非常に長い文字列を取得します。

私はこれを回避する方法があるに違いないと思いますが、私は何を理解することができません。本当に奇妙なことは、上記のフルネームを持つタイプは、それ自体がGenericTypeではない、またはGenericTypeParametersを持っていると報告することです。これは私には完全に間違っているようです。誰かがこれの問題と対応する回避策が何であるか知っていますか？

代わりにNDoc3を使用するように切り替えることができますが、この問題はありませんが、そのプロジェクトはソースコードを公開していないため、自分で調べることはできません。

誰かが私の好奇心を満たし、私を啓発することができますか？

マイクロソフトは、サンドキャッスルのCTP /ベータバージョンをリリースしたときにNDocを殺しました。また、使用可能なバージョンのサンドキャッスルの新しいバージョンに関する情報（たとえば、統合されたUIを備えたもの）はめったに見られません。最新のリリースは2008年5月のリリースです。Sandcastleは死んだプロジェクトですか、それともVisual Studio 2010に含まれますか？

NDOC3 を使用してプロジェクト ドキュメントに取り組んでいます。

サードパーティの DLL をドキュメント化しようとすると、ビルドが失敗します (それらの xml ドキュメントがないため)。この問題にどのように対処できますか?

作成したばかりの新しいコードを調べて、NDoc スタイルのコメントをクラスとメソッドに追加しています。参照用にかなり優れた MSDN スタイルのドキュメントを生成したいと考えています。

一般的に、クラスやメソッドにコメントを書く際の良いガイドラインは何ですか? NDoc コメントは何を言うべきですか? 彼らは何を言うべきではありませんか？

.NET フレームワークのコメントに書かれている内容を見ていると、すぐに古くなってしまいます。自分自身を導くための良いルールがあれば、ドキュメントをはるかに速く完成させることができます.

クラスに次のような XML コメントがあるとします。

フレームワークのドキュメントの適切なページへの参照System.Threading.Thread.CurrentPrincipalとリンクを取得するにはどうすればよいですか?System.Web.HttpContext.User

.NET Framework 3.5 を使用して、フレームワーク 3.5 をサポートする nant -0.91-alpha2 を使用していますが、ドキュメントをビルドしようとすると次のエラーが発生します。

ドキュメントは、次のように生成されます。