Dokumentation über Schnittstellenimplementierungen duplizieren / gut oder schlecht überschreiben?

Wir haben also eine Schnittstelle wie diese

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

Kürzlich haben wir eine Dokumentationsstory gespielt, in der es darum ging, wie oben beschrieben, eine ausreichende Menge an XML-Dokumentation zu generieren und sicherzustellen. Dies verursachte jedoch eine Menge Doppelarbeit in der Dokumentation. Beispielimplementierung:

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

Wie Sie sehen können, ist die Methodendokumentation ein direkter Rip von der Oberfläche.

Die große Frage ist, ist das eine schlechte Sache? Mein Bauch sagt mir ja wegen der Vervielfältigung, aber vielleicht auch nicht?

Wir haben auch eine ähnliche Vervielfältigung der Dokumentation mit overrideFunktionen und virtualFunktionen.

Ist das schlecht und sollte vermieden werden oder nicht? Lohnt es sich überhaupt noch?

c# documentation xml documentation-generation

— Earlz
quelle

Wenn Sie Resharper verwenden, können Sie Kommentare nur in der Implementierung ändern und anschließend die Benutzeroberfläche mithilfe von "Mitglieder nach oben ziehen" aktualisieren.

— Vortexwolf

Ich mache das aber vielleicht, weil ich nicht so gut mit externen Tools umgehen kann und es vorzuziehen bin, einfach in die Header-Datei einer Schnittstelle zu navigieren, um zu sehen, was ich mit einer bestimmten Art von Dingen machen kann (dies ist für C und C ++, die sich trennen) der Begriff des Headers aus der Quelldatei). Es wiederholt sich ein bisschen, aber ich versuche, Möglichkeiten zu finden, um spezifischere Details in Bezug auf die konkrete Klasse hinzuzufügen, die die Methoden überschreiben. Ich mag es z Siehe Kommentare für jede Funktion in einer Header-Datei.

Ich verwende eigentlich Doxygen-Kommentare und -Tags, aber ich sehe mir die Dokumente beim Codieren nicht so genau an. Ich ziehe es vor, einfach zur Header-Datei zu navigieren und zu sehen, was ich mit etwas anfangen kann. Könnte nur ein Fall sein, bei dem ein alter Hund Schwierigkeiten hat, neue Gewohnheiten und Werkzeuge zu erlernen.

Im Allgemeinen würde ich den Methoden der Implementierung nur dann eine neue Dokumentation hinzufügen, wenn an dieser Implementierung etwas Besonderes zu erwähnen ist.

In javadoc können Sie Verknüpfungen zu anderen Methoden herstellen, sodass Sie in der Implementierung lediglich eine Verknüpfung zur Methodendokumentation in der Schnittstelle erstellen können. Ich denke, so soll es in .Net gemacht werden (basierend auf meiner Lektüre der Online-Dokumentation, nicht meiner eigenen Erfahrung):

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

Die Dokumentation zum <see/>Element: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

— FrustratedWithFormsDesigner
quelle

Wie wäre es mit dem Überschreiben der XML-Dokumente in einer geerbten Klasse? Angenommen, ich mache eine Unterklasse aus Collection<T>und möchte deren CountEigenschaft XML-Dokumente überschreiben .

— Shimmy