web-dev-qa-db-ja.com

インターフェースの実装に関するドキュメントを複製する/良いか悪いかをオーバーライドしますか？

だから私たちはそのようなインターフェースを持っています

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

最近、私たちは、上記のようなXMLドキュメントがたくさんあることを生成して確認することを含むドキュメントストーリーをプレイしました。これにより、ドキュメントの重複が多く発生しました。実装例：

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

あなたが見ることができるように、メソッドのドキュメントはインターフェースからの直接のリッピングです。

大きな問題は、これは悪いことですか？重複のために私の腸はイエスと私に言いますが、それでも多分そうではありませんか？

また、override関数とvirtual関数を使用した他の同様のドキュメントの重複があります。

これは悪いことであり、回避すべきかどうか。それはまったく価値がありますか？

c#documentationxmldocumentation-generation
20
Earlz

一般的に、that実装について言及する必要がある特定の事項がある場合にのみ、実装のメソッドに新しいドキュメントを追加します。

Javadocでは、他のメソッドにリンクできます。これにより、実装のリンクをインターフェースのメソッドドキュメントに作成できます。私はこれが.Netで行われるはずの方法だと思います（私自身の経験ではなくオンラインドキュメントを読んだことに基づいています）：

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// <see cref="ICreatesFoo.Create(Foo)"/>
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// <see cref="ICreatesFoo.Bar()"/>
  /// Also Note: Implementation of Bar() in FastFooCreator
  /// requires a minimum of 512 MB RAM to Bar the Foo. 
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

<see/>要素のドキュメント： http://msdn.Microsoft.com/en-us/library/acd0tfbe.aspx

9
FrustratedWithFormsDesigner