ทำสำเนาเอกสารเกี่ยวกับการใช้งานอินเตอร์เฟส / แทนที่ดีหรือไม่ดี?

ดังนั้นเราจึงมีส่วนต่อประสานเช่นนั้น

/// <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ฟังก์ชั่น

สิ่งนี้เลวและควรหลีกเลี่ยงหรือไม่? มันคุ้มค่าหรือไม่?

โดยทั่วไปแล้วผมเพียงต้องการเพิ่มเอกสารใหม่กับวิธีการดำเนินการที่ว่ามีบางสิ่งบางอย่างที่เฉพาะเจาะจงเกี่ยวกับว่าการใช้งานที่ตอบสนองความต้องการที่จะกล่าวถึง

ใน 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