Duplicazione della documentazione sulle implementazioni dell'interfaccia / annullamento buono o cattivo?

Question

Duplicazione della documentazione sulle implementazioni dell'interfaccia / annullamento buono o cattivo?

#1 da (7 voti)

14

Quindi abbiamo un'interfaccia come questa

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

Recentemente, abbiamo svolto una storia di documentazione che prevedeva la generazione e l'assicurazione che ci fosse abbondanza di documentazione XML come sopra. Ciò ha causato un sacco di duplicazione della documentazione però. Implementazione di esempio:

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

Come puoi vedere la documentazione del metodo è un'interfaccia diretta dall'interfaccia.

La grande domanda è, è una cosa brutta? Il mio istinto mi dice sì a causa della duplicazione, ma di nuovo forse no?

Inoltre, abbiamo altre duplicazioni di documentazione simili con funzioni override e funzioni virtual .

Questo è cattivo e dovrebbe essere evitato, o no? Ne vale davvero la pena?

c# documentation xml documentation-generation

posta Earlz 04.04.2013 - 17:31

fonte

1 risposta

Leggi altre domande sui tag c# documentation xml documentation-generation

Licenza per applicazione freeware ma closed source Le università senza scopo di lucro che offrono corsi di laurea in informatica in linea? [chiuso]

score 7 · Answer 1

In generale, aggiungerei solo nuova documentazione ai metodi di implementazione se c'è qualcosa di specifico sull'implementazione che che deve essere menzionata.

In javadoc puoi collegare ad altri metodi, il che ti permetterebbe semplicemente di creare un collegamento nell'implementazione alla documentazione del metodo nell'interfaccia. Penso che questo è come dovrebbe essere fatto in. Net (basato sulla mia lettura della documentazione online, non sulla mia esperienza):

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

La documentazione per l'elemento <see/> : link