Arabirim uygulamaları / geçersiz kılma belgelerinin kopyalanması iyi mi kötü mü?

Yani böyle bir arayüzümüz var

/// <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();
}

Son zamanlarda, yukarıdaki gibi çok sayıda XML dokümanının oluşturulmasını ve sağlanmasını içeren bir dokümantasyon hikayesi oynadık. Bu, belgelerin çoğalmasına neden oldu. Örnek uygulama:

/// <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
  }
}

Gördüğünüz gibi, dokümantasyon arayüzden düz bir rip.

Büyük soru şu, bu kötü bir şey mi? Bağırsaklarım yineleme nedeniyle evet diyor, ama sonra tekrar değil mi?

Ayrıca, overrideişlevler ve virtualişlevlerle benzer başka belge çoğaltmamız var .

Bu kötü mü ve kaçınılması mı gerekiyor, değil mi? Hatta buna değer mi?

c# documentation xml documentation-generation

— Earlz
kaynak

Yeniden Paylaşıcı kullanıyorsanız, yorumları yalnızca uygulamada değiştirebilir ve sonra "Üyeleri yukarı çek" i kullanarak arabirimi güncelleyebilirsiniz.

— vortexwolf

Bunu yapıyorum ama belki de harici araçları kullanarak çok iyi değilim ve sadece belirli bir tür şeyle ne yapabileceğimi görmek için bir arabirimin başlık dosyasına gitmeyi tercih ettiğimden (bu C ve C ++ için ayrı kaynak dosyadan başlık kavramı). Biraz tekrarlı oluyor ama yöntemleri geçersiz kılan somut sınıfla ilgili daha spesifik detaylar eklemek için fırsatlar bulmaya çalışıyorum, örneğin hoşuma gitti ve eğer yapmazsam önemli bir şeyi atladığımı hissettiğim bir OKB şeyim var başlık dosyasındaki her işlevin açıklamalarına bakın.

Aslında Doxygen yorum ve etiketlerini kullanıyorum ama aslında kodlama sürecinde belgelere çok fazla bakmıyorum. Sadece başlık dosyasına gitmeyi ve bir şeyle neler yapabileceğimi görmeyi tercih ediyorum. Yeni alışkanlıkları ve araçları almakta zorlanan yaşlı bir köpeğin vakası olabilir.

İlgili bir şey özgü varsa Genel olarak, ben sadece uygulama yöntemlerine yeni belgelere eklemek istiyorum bu ihtiyaçların belirtilmesi gereken bu uygulamaya.

Javadoc'ta, arayüzde yöntem belgelerine uygulamada bir bağlantı oluşturmanıza izin veren diğer yöntemlere bağlantı verebilirsiniz. Ben bunun böyle yapılması gerektiğini düşünüyorum. Net (kendi deneyimimi değil, çevrimiçi belgeleri okuma dayalı):

/// <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/>Öğenin belgeleri : http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

— FrustratedWithFormsDesigner
kaynak

Devralınan bir sınıfta XML belgelerini geçersiz kılmaya ne dersiniz? Diyelim ki bir alt sınıf oluşturuyorum Collection<T>ve onun Countözellik XML belgelerini geçersiz kılmak istiyorum .

— Shimmy