Den korte version:

GhostDoc hjælper Visual Studio (VB.NET og C#) udviklere med at lave XML dokumentationskommentarer ved at generere simple default beskrivelser.

Den lidt længere version:

Hvis man systematisk laver XML dokumentationskommentarer i ens kode, finder man hurtigt ud af, at det er en ikke helt triviel opgave, der hurtigt kommer til at løbe op i en ikke uanseelig arbejdsbyrde - ihvertfald hvis det skal være bare nogenlunde udtømmende og forståeligt. Man finder også ud af, at mange af kommentarer typisk opbygges ved en ikke ringe mængde copy-paste fra andre allerede dokumenterede metoder - i sig selv ikke det mest ophidsende og berigende stykke arbejde man kan beskæftige sig med.

Når udvikleren skriver tre kommenteringstegn (/// i C# og ''' i VB.NET) indsætter Visual Studio automatisk en række XML-tags for at lette udviklerens arbejde med at skrive dokumentationen. GhostDoc går en tand videre, idet dette værktøj også indsætter egentlig tekst i kommentarerne. Den indsatte tekst baserer sig på et konfigurerbart regelsæt og udledes fra såvel type- som navnemæssige informationer i sourcekoden.

Bemærk at understøttelse af VB.NET først er kommet til for nylig. I den nuværende version skal man derfor eksplicit slå VB.NET understøttelsen til i GhostDoc-konfigurationen (på "Options"-fanebladet).

Man kan generere dokumentationskommentarer ved at vælge "Document this" i kode-editorens kontekstmenu, ved at vælge "GhostDoc|Document this" i Visual Studios "Tools"-menu eller via en tastatur-shortcut (som default Ctrl-Shift-D).

Tag som eksempel følgende overriding af System.Object-klassens GetHashCode-funktion:

public override int GetHashCode()
{
  return this.Id.GetHashCode();
}

Visual Studio genererer følgende XML dokumentations kommentar:

/// <summary>
///
/// </summary>
/// <returns></returns>
public override int GetHashCode()
{
  return this.Id.GetHashCode();
}

GhostDoc genererer til sammenligning følgende XML dokumentationskommentar:

/// <summary>
/// Serves as a hash function for a particular type. <see cref="M:System.Object.GetHashCode"></see> is suitable for use in hashing algorithms and data structures like a hash table.
/// </summary>
/// <returns>
/// A hash code for the current <see cref="T:System.Object"></see>.
/// </returns>
public override int GetHashCode()
{
  return this.Id.GetHashCode();
}

Her er der naturligvis tale om et ret ekstremt tilfælde, idet det for de fleste nok tager væsentligt længere tid at skrive dokumentationen end at lave den meget trivielle implementation. Men mon ikke de fleste udviklere nok trods alt laver en hel del meget triviel kode, så der samlet set er en hel del tid at spare ved at benytte GhostDoc.

Selvom GhostDoc er overraskende god til, at lave dokumentation, der giver ganske god mening - ihvertfald lige så god mening som den dokumentation man selv (og for den sags skyld Microsoft) er i stand til at lave, så bør man trods alt kun betragte den genererede tekst som et udgangspunkt. Man bør altid gennemlæse teksten grundigt, rette hvad der rettes bør samt tilføje yderligere relevante og nødvendige informationer. Man kan naturligvis ikke nøjes med GhostDocs kommentarer; dertil er de i sagens natur holdt i alt for generelle vendiger.

Ud over at man kan spare tid ved at få GhostDoc til at generere udgangspunktet for ens kommentarer er en ekstra fordel at man ihvertfald i forbindelse med standard metoder og parametre får en højerere grad af konsistens af ens kommentarer.

GhostDoc kan kun generere XML dokumentationskommentarer for metoder og properties (og herunder henholdsvis konstruktører og indexers). Fields, events, klasser og så videre er desværre ikke understøttet. Men det man rent faktisk får, er så sandelig også værdifuldt i sig selv.

Download:

Download af GhostDoc