Förord

Dokumentation av programvara är ett viktigt område som folk ofta väljer att spendera väldigt lite tid på. Doxygen är ett verktyg som hjälper dig att enkelt skapa en uppdaterad och användbar dokumentation på ett enkelt sätt.

Innehåll

  » Introduktion
  » Doxygen
  » Kommentering av koden
  » Körning av Doxygen

Introduktion

Dokumentation av programvara är ett viktigt område som folk ofta väljer att spendera väldigt lite tid på. Det finns flera tillfällen då dokumentation är viktigt / nödvändigt, här är några av dem:

• Krav från beställare av program.
• Utveckling i grupp tillsammans med andra.
• Utveckling av större program.

En beställare av ett program vill vanligtvis ha någon form av dokumentation om de tänkt vidareutveckla programmet. Dokumentationen görs ofta efter programmet är färdigt, eller när programmeraren har lust. Vid sporadisk dokumentation blir det ofta knapphändigt och de kryptiska kodrader som verkade självklara för dig när du skrev dem igår kanske inte är det ett halvår framåt i tiden. Om man istället väljer att dokumentera allt i slutändan leder det ofta till inkonsekvent kod då man har svårt att se koden i ett ”helhetsperspektiv” under programmeringens gång.

När program eller projektgrupper växer ökar inte effektiviteten linjärt mot antalet spenderade timmar eller medlemmar i gruppen. Dokumentationen ger en bra översikt för alla i gruppen, och möjligheten att förstå funktionen hos kod man inte själv har skrivit. Detta är nödvändigt i större projekt då det tar lång tid att läsa källkod, men går snabbt att läsa bra dokumentation.

Dokumentation är inte bara för dig som arbetar i grupp. När ett program blir tillräckligt stort kommer du börja glömma bort saker som du tidigare gjort. Ett vanligt fel är ”dangling methods / dangling variables”, metoder som en gång användes men inte längre har någon funktion. Detta är svårt att se i källkod, men enkelt att se i bra dokumentation.

Doxygen

Doxygen är ett verktyg som hjälper dig som programmerare att skriva bra dokumentation. Doxygen hanterar mängder med språk; C, C++, Java, Objective-C, Python, IDL, PHP, C# och D. Grundtanken är att dokumentera sitt program genom kommentarer i själva koden. Doxygen genererar sedan färdig dokumentation i t.ex. HTML utifrån dina källkodsfiler. Du behöver alltså inte skriva separat dokumentation utan allt sköts genom särskilda kommentarer i källkoden. Detta leder till att du får en snygg dokumentation tillsammans med väldokumenterad källkod.

Doxygen går att hämta från http://www.doxygen.org, installationen är enkelt och inget som jag går igenom här. Se bara till att installera ”doxywizard GUI” samt ”Doxygen manual”.

Kommentering av koden

Du kan välja att dokumentera varenda privat obskyr variabel eller bara göra översiktsdokumentation över klasserna. Vad man dokumenterar är upp till var och en, men att dokumentera alla publika variabler och metoder brukar vara en bra start för många.
För att doxygen ska veta vad som skall dokumentateras använder man en särskild slags kommentarer. Det finns olika sätt att skriva kommentarerna, sättet jag visar här kallas JavaDoc.


/** Brief description.
* Detailed description.
* @param text The text to speak.
* @return 1 on success, 0 if the cow is too tired to speak right now.
*/
bool sayMooh(std::string text);


Brief description är endast en mening lång, och beskriver det du dokumenterar på ett kort och enkelt sätt. En detailed description kan vara hur lång som helst.

Rader som börjar med @ särbehandlas av Doxygen. @param betyder en parameter till metoden. I exemplet ovan har metoden en parameter som heter ’text’ som berättar vad kon ska säga. Syntaxen är alltså @param .
@return används för att dokumentera returvärdet hos metoder.
Det finns mängder av dessa @-kommandon, men vanligtvis använder man bara ett fåtal. Se ”Documenting the code” i manualen för mer ingående information om dessa.

Nedan följer det exempel jag använt för att generera dokumentation. Det är inte vettigt med avseende på vare sig kod eller funktion, men duger gott som exempel att dokumentera.


#include
#include

/** Base class for all the animals in the world.
* A detailed description should go here.
*/
class Animal
{
public:
/** Walk the animal.
* @param direction 1 = west, 2 = east.
*/
void walk(int direction)
{}

protected:
std::string race; /**< The race of the animal */
};

/** This is a representation of the glorious cow.
* Some say the cow is the best animal in the world.
*/
class Cow : public Animal
{
public:
/** Have the cow say something.
* @param text The text to speak.
* @return 1 on success, 0 if the cow is too tired to speak right now.
*/
bool sayMooh(std::string text)
{
std::cout << text << ". Mooh!\n";

return 1;
}
};

int main()
{
Cow c;

c.sayMooh("I am a cow");

return 0;
}


Körning av Doxygen

Då var det äntligen dags att generera dokumentation. För att göra detta startar du doxywizard. Använd wizarden första gången, då doxygen har otroligt många inställningsmöjligheter i expert mode. Wizarden är lätt att förstå och det är bara att fylla i alla fält. Checkboxen ”Scan recursively” under ”Project” kan vara bra att kryssa i om din källkod ligger i undermappar. ”All entities” under ”Mode” är också användbar, eftersom även odokumenterad kod kommer med i dokumentation då.

För att se dokumentationen som genererades av kodsnutten ovan, klicka här.

Detta har bara varit en kort introduktion till Doxygen, men förhoppningsvis nog för att du själv ska kunna fortsätta att använda det. Dokumentation är aldrig kul att skriva, men ibland är det nödvändigt. Det är då hjälpmedel som Doxygen kan vara bra att ha i verktygslådan.

0 Kommentarer

Skriv en kommentar på artikeln

Ditt betyg på artikeln

UtmärktLäsvärdIntressantMindre braDålig

Kommentar: