Kommentare auf Interface/Implementierung abgleichen

04/03/2010 - 16:59 von christoph.rabel | Report spam
Hi!

Wir haben hier ein hübsches kleines Projekt, mit dutzenden Interfaces
und deren Implementierungen.

Nun wurden im Laufe der Zeit mal hier, mal hier die Methoden
Kommentare upgedated. Manchmal stimmen die Kommentare im Interface
überein, manchmal nicht, manchmal steht da sogar ganz was anderes weil
die Methode refactored wurde und nur bei der Implementierung
(vielleicht) der Text geàndert wurde.

Kennt zufàllig irgendwer ein Tool, das mir dabei hilft? Ich möchte
nicht Interface für Interface manuell durchschauen müssen und mir bei
allen Implementoren die Kommentare die dort stehen raussuchen,
vergleichen,...

Danke für alle Tipps, Christoph
 

Lesen sie die antworten

#1 Immo Landwerth
04/03/2010 - 17:38 | Warnen spam
wrote:

Wir haben hier ein hübsches kleines Projekt, mit dutzenden Interfaces
und deren Implementierungen.

Nun wurden im Laufe der Zeit mal hier, mal hier die Methoden
Kommentare upgedated. Manchmal stimmen die Kommentare im Interface
überein, manchmal nicht, manchmal steht da sogar ganz was anderes weil
die Methode refactored wurde und nur bei der Implementierung
(vielleicht) der Text geàndert wurde.

Kennt zufàllig irgendwer ein Tool, das mir dabei hilft? Ich möchte
nicht Interface für Interface manuell durchschauen müssen und mir bei
allen Implementoren die Kommentare die dort stehen raussuchen,
vergleichen,...



Ich nehme an, Du sprichst von XML Kommentaren für die Dokumentation und
möchtest, dass in dem folgenden Beispiel:

interface IFoo
{
/// <summary>
/// This is bar.
/// </summary>
void Bar();
}


class Foo : IFoo
{
/// <summary>
/// This is bar but with addtional info not present in IFoo's
/// declaration of Bar.
/// </summary>
public void Bar()
{
}
}

die Doku von IFoo.Bar und Foo.Bar konsistent ist, was in meinem Beispiel
nicht der Fall ist.

Ich kenne kein Tool, was Dir die Inkonsistenzen aufzeigen würde.
Vielleicht gibt es dafür ein ReSharper Plug-In oder vielleicht kann es
auch GhostDoc.

Es gibt aber auch die Möglichkeit, die Wurzel des Problems zu
addressieren und auf das sinnlose kopieren zu verzichten. Wenn Du z.B.
Sandcastle mit dem Sandcastle Help File Builder verwendest, kannst Du
dafür das <inheritDoc /> Tag verwenden:

[Using the <inheritdoc /> Tag]
http://www.ewoodruff.us/shfbdocs/In...7e50da.htm

Wesentliches aus dem verlinkten Artikel:

- XML Kommentar werden für Schnittstellen autmatisch vererbt, wenn sie
ganz weggelassen werden.

- Wenn man z.B. nur das <summary> übernehmen möchte, aber das <returns>
neu verfassen möchte, kann man das o.g. <inheritDoc /> Tag verwenden:

/// <inheritdoc />
/// <returns>This is a dummy class so it throws an exception</returns>
IEnumerator IEnumerable.GetEnumerator()
{
// In this case, we automatically inherit the base interface's
// <summary> but override the <returns> documentation. As above,
// because we specified comments, we have to add the <inheritdoc />
// tag too.
throw new Exception("The method or operation is not implemented.");
}

Immo Landwerth

Ähnliche fragen