Softwaredocumentatie met Sandcastle
Waarom verschijnt er altijd een ongemakkelijke glimlach op het gezicht van een ontwikkelaar als er gevraagd wordt of zijn software gedocumenteerd is? Hoewel deze vraag niet wordt beantwoord in dit artikel, zal er worden uitgelegd hoe het op eenvoudige wijze mogelijk is om (technische) documentatie van software automatisch te laten genereren.
IntelliSense
De ontwikkelomgeving Visual Studio van Microsoft biedt een ontwikkelaar veel hulpmiddelen die gebruikt kunnen worden om gemakkelijk software te kunnen schrijven. Een van deze hulpmiddelen is de zogenaamde IntelliSense. Reeds tijdens het intypen van de code analyseert de compiler van Visual Studio de software en geeft op basis daarvan hints en tips aan de ontwikkelaar. Deze hints en tips beperken zich in eerste instantie tot het geven van technische informatie over de werking van bepaalde statements en hoe programmafuncties aangeroepen dienen te worden. Het geven van begrijpbare functionele uitleg ontbreekt hier natuurlijk. Gelukkig is het wel mogelijk om handmatig deze uitleg toe te voegen aan de IntelliSense van Visual Studio door middel van het definieren van XML-comments. Deze worden vaak genoemd als triple-slash-comments.
XML-comments als input voor generatie van technische documentatie
De naamgeving triple-slash-comments is ontstaan vanwege het feit, dat een dubbele slash gebruikt wordt om commentaar in een C, C++ of C# listing op te nemen. Specifiek commentaar voor IntelliSense wordt gedefinieerd door een drievoudige slash. Bij het gebruik van Visual Basic als programmeertaal worden geen slashes gebruikt maar het apostrofteken. Daar waar in C# een drievoudige slash wordt gebruikt, wordt in Visual Basic een drievoudige apostrof gebruikt. In de volgende listings is een voorbeeld weergegeven voor zowel C# als Visual Basic, dat laat zien hoe de IntelliSense van Visual Studio het commentaar van de functie GetFilename weergeeft.
Fig. 1: IntelliSense C#
Fig. 2: IntelliSense Visual Basic
Veel ontwikkelde software wordt als een library gedistribueerd (class-library). Andere softwareontwikkelaars kunnen naar deze libraries referenties leggen om daaruit onderdelen te gebruiken. Natuurlijk is het wenselijk dat de IntelliSense, die is uitgebreid met de triple-slash-comments, ook voor deze ontwikkelaars beschikbaar komt. Omdat triple-slash-comments geen onderdeel zijn van de gecompileerde programmacode, zou je verwachten dat ook de listing meegeleverd moet worden. Gelukkig is dit niet het geval en biedt Visual Studio de mogelijkheid om uitsluitend alle triple-slash-comments in een speciaal bestand op te slaan. De gedistribueerde software bestaat dus uit twee onderdelen: de gecompileerde programmacode (DLL-bestand) en de triple-slash-comments ten behoeve van de IntelliSense (XML-bestand). In de volgende afbeelding is zichtbaar waar in het properties-scherm geconfigureerd wordt dat Visual Studio een dergelijk XML-bestand dient te genereren (deze optie staat standaard uit).
Fig. 3: Propertiesscherm
Sandcastle
Naast het IntelliSense mechanisme dat volledig is geintegreerd in de Visual Studio ontwikkelomgeving, zijn er nog andere hulpmiddelen die gebruik maken van de triple-slash-comments. Een van deze hulpmiddelen is een door Microsoft ontwikkeld product dat voorlopig nog de codenaam Sandcastle draagt. Sandcastle is een product dat op basis van de door Visual Studio geleverde XML-bestanden technische documentatie kan genereren van de ontwikkelde programmacode. Deze gegenereerde documentatie bevat naast alle teksten die via triple-slash-comments door een ontwikkelaar zijn ingevoerd, ook alle teksten die door ontwikkelaars van Microsoft zijn ingevoerd. Dit laatste geldt natuurlijk alleen voor gemeenschappelijke functies die zowel in de eigen ontwikkelde software als ook in het .NET Framework aanwezig zijn. Daarnaast bevat de gegenereerde documentatie ook verwijzingen naar de MSDN-website van Microsoft waar de volledige documentatie van het .NET Framework te vinden is. In de volgende afbeelding is zichtbaar hoe de gegenereerde software documentatie door Sandcastle er uitziet. De look-and-feel van de documentatie vertoont veel gelijkenis met die van de MSDN-website van Microsoft. Op zich is dit niet raar aangezien insiders bij Microsoft bevestigd hebben dat ook Microsoft gebruik maakt van Sandcastle.
Fig. 4: Gegenereerde documentatie door Sandcastle
Sandcastle is niet het eerste product dat op basis van XML-comments in staat is om documentatie te genereren van de programmacode. De meeste ontwikkelaars hebben vast wel eens gehoord van NDoc. Dit opensource project was een van de eerste die volledig geautomatiseerd een helpbestand kon genereren in diverse bestandsformaten. Helaas is dit project stopgezet door de auteur van NDoc omdat hij niet of nauwelijks hulp kreeg vanuit de community om het product verder te ontwikkelen en geschikt te maken voor de nieuwere versies van .NET. Het antwoord van Microsoft kon daarom niet uitblijven en zo kwam het project van de grond, dat nu de codenaam Sandcastle draagt.
Werking van Sandcastle
De werking van Sandcastle bestaat uit een aantal aaneen geschakelde verwerkingsstappen. Als eerste wordt via Visual Studio de programmacode gecompileerd. Dit resulteert in twee soorten bestanden namelijk de gecompileerde programmacode (DLL-bestand) en de XML-comments (XML-bestand). Vervolgens zal het DLL-bestand door Sandcastle worden geanalyseerd. Dit is te vergelijken met de analyse die de compiler van Visual Studio uitvoert ten behoeve van de IntelliSense. De uitvoer van deze analyse levert een aantal XML-bestanden op. Deze bestanden worden via een aantal XSLT-transformaties samengevoegd met de door Visual Studio gegenereerde XML-comments-bestanden en omgevormd tot leesbare HTML-bestanden. Deze HTML-bestanden worden uiteindelijk via een HTML-helpbuilder gecompileerd tot een HLP- en/of CHM-bestand. In de volgende afbeelding zijn de verwerkingsstappen van Sandcastle weergegeven.
Fig. 5: Sandcastle documentatieproces
Sandcastle beschikt niet over een (gebruiksvriendelijke) user interface. De reden hiervoor is voor buitenstaanders nog een beetje speculeren, maar dit heeft hoogstwaarschijnlijk te maken met het feit Microsoft het gebruik van Sandcastle ziet als onderdeel van een geautomatiseerd build-proces (wat vaak tijdens een nachtelijke run plaatsvindt). Gelukkig zijn er door een aantal leden van de Microsoft community diverse tools gemaakt die voorzien zijn van een user interface en die Sandcastle onder water configureren en aansturen. Deze maken het gebruik van Sandcastle, dat vooralsnog beschikt over een command-line interface, eenvoudiger. Deze tools worden door Microsoft ook aanbevolen om te gebruiken.
Conclusie
Steeds meer bedrijven erkennen dat het beschikken over goede documentatie een essentieel onderdeel is van het proces dat softwareontwikkeling heet. Omdat er steeds hogere eisen gesteld worden aan de kwaliteit van dergelijke documenten, neemt ook de tijd die nodig is om documentatie schrijven toe. Het gebruik van adequate tooling om dit proces te versnellen is dan ook een onmisbaar onderdeel. Met behulp van Microsoft’s Sandcastle kan op eenvoudige en snelle wijze een overzichtelijke technische documentatie worden gegenereerd van de ontwikkelde software. Het is vanzelfsprekend dat het uitsluitend beschikken over technische documentatie niet voldoende is en er moet onderkend worden dat de aanwezigheid van functionele documentatie minstens zo belangrijk is. Microsoft’s Sandcastle mag gezien worden als een goede aanvulling op de hulpmiddelen die bijdragen aan het schrijven van documentatie van software.
Meer informatie over Sandcastle, de syntaxis van XML-comments en de beschikbare user interfaces voor Sandcastle kan gevonden worden op de volgende websites: