6

ソース コードの一部を XML ドキュメントに追加したいと思います。次のように、ソース コードをいくつかの <code> 要素にコピー & ペーストできます。

/// <summary>
/// Says hello world in a very basic way:
/// <code>
///   System.Console.WriteLine("Hello World!");
///   System.Console.WriteLine("Press any key to exit.");
///   System.Console.ReadKey();
/// </code>
/// </summary>
static void Main() 
{
    System.Console.WriteLine("Hello World!");
    System.Console.WriteLine("Press any key to exit.");
    System.Console.ReadKey();
}

これを維持するのは苦痛でしょう。C# の XML ドキュメントにソース コードを追加する可能性は他にありますか?

Sandcastle で XML ドキュメントを処理しており、そこからテクニカル ヘルプ ファイル (*.chm) を作成したいと考えています。そのヘルプ ファイルに、一部または完全なメソッド本体を追加したいと考えています。

編集: slide_rule からのコメントをありがとう。より現実的であまり自明ではない例を追加しました。

次のようなメソッドがあるとします。

public decimal CalculateFee(Bill bill)
{
    if (bill.TotalSum < 5000) return 500;
    else
    {
        if (bill.ContainsSpecialOffer) return bill.TotalSum * 0.01;
        else return bill.TotalSum * 0.02;
    }
}

料金の計算方法に関する情報をテクニカル ヘルプ ファイルに追加できると便利です。

最も明白な解決策は、アルゴリズムを平凡なテキストとしてコメントに書き留めることです。

別の解決策は、メソッドの本文をコピーしてコメント フィールドに貼り付け、それを <code> 要素に入れることです。このメソッド本体は、C# についてあまり知識がなくても非常に簡単に理解できます。そのため、テクニカル ヘルプ ファイルに記述しても問題はありません。

どちらのソリューションも DRY の原則に違反しています。情報を複製せずに、メソッド本体またはメソッド本体の一部をヘルプ ファイルに追加したいと考えています。

これはC#で可能ですか? (RDoc for Ruby はこれを行うことができると思いますが、C# での解決策が必要です)

4

4 に答える 4

1

私にとって、コメントの主な目的はコードを説明することです。コードをコピーして貼り付けるだけではその目的は達成されないので、私の質問は「ドキュメントの意図された目的は何ですか？」だと思います。メソッドを呼び出す人にメソッドが何をするかを文書化しますか（APIドキュメントのようなもの）、または別の開発者がソースコードを維持できるように、メソッドがどのように機能するかを文書化しますか？または何か違う？

それが最初の場合、私はコードを使用します。この方法では、割引のさまざまなルールとアルゴリズムに含まれているものを考慮して料金を計算します。これらの計算のビジネスルールは、重要な情報ではなくAPIコンテキストにあり、APIを変更せずに変更される可能性があります（インターフェイスの背後にある実装のみが変更されます）

それが2番目の目的である場合、コードを繰り返しても目的は達成されません。何かを繰り返すとそれがより明確になり、何かを繰り返すとそれがより明確になりますが、メソッドの使用方法の例が説明に役立つ場合があります。使用例は繰り返しではなく、メソッドシグネチャが変更された場合にのみ変更する必要があり、その後、ドキュメントの変更が必要になります

于 2009-06-25T06:36:30.120 に答える
1

そこにアイデアを投げるだけです...

何らかの方法で区切られたコードブロックを探すプロセスを自動化し、そのコードをXMLコメントに挿入します。

/// <summary>
/// Says hello world in a very basic way:
/// <code>
///     Code block 1
/// </code>
/// </summary>
static void Main() 
{
    // Code block 1 start
    System.Console.WriteLine("Hello World!");
    System.Console.WriteLine("Press any key to exit.");
    System.Console.ReadKey();
    // Code block 1 end
}

かわいくないことは知っていますが、それは始まりです！;）

于 2009-06-25T01:07:18.400 に答える
1

次のようなフィールドを使用してコードを文書化するためのより標準的なアプローチを採用してみませんか

<summary>
   <description>Displays Hello World!</description>
   <arguments>None</arguments>
   <returns>None</returns>
</summary>

ちょっとした考え。

于 2009-06-25T01:22:46.153 に答える
0

include 要素をいじってみるといいかもしれません。私はそれを使用したことがないので、その要素を他の通常の XML コメント要素と混在させることができるかどうかはわかりませんが、(まばらな) ドキュメントを読んだ方法では、そのようには見えません。

それが最善の選択肢ですが、それが不可能な場合でも、その要素の使用を、関連するコード部分を見つけて XML ファイルに挿入するスクリプトと組み合わせることができる場合があります。

多分別のルートを選ぶだろうけど。XML コメントの出力は単なる XML ファイルであるため、作成後、Sandcastle を実行する前に処理できます。次に、ヘルプ ファイルに入力する必要があるすべてのコードを検索する別のスクリプトを作成し、それを別の XML ファイルに抽出します。

これら 2 つの XML ファイルは、XSLT を使用してマージし、SandCastle に渡すことができます。

ヘルプ ファイルに入れる必要があるコードをどのように特定しますか? 頭のてっぺんから、次の 3 つのオプションを考えることができます。

  • 属性
  • 地域
  • コメント

個人的にはアトリビュートの方が好きです。

締めくくりとして、これは確かに可能ですが、コピーして貼り付けて少し規律を保つよりもおそらく多くの作業があることを指摘したいと思います:)

于 2009-06-25T07:15:28.827 に答える