Dokumentera PHP med phpdoc och phpDocumentor

Du ska dokumentera ditt projekt med phpdoc och phpDocumenter. Det handlar om att dra nytta av dina docblock kommenterarer när du nu skall automatgenerera din dokumentation.

Du har ett befintligt projekt där din Makefile redan innehåller stöd för att använda phpdoc för att generera dokumentationen.

Så här kan det se ut när du löst uppgiften.

#Förkunskaper

Du har tillgång till ett projekt med en Makefile som stödjer att installera phpdoc och generera dokumentation.

Du är bekant med phpDocumenter, aka phpdoc.

Du är medveten om behovet av kommentarer strukturerade som docblock, för att få en bra grund till dokumentationen.

#Introduktion

Det handlar om att använda phpDocumenter via kommandot phpdoc för att automatgenerera dokumentation av dina klasser i ditt projekt. Du kommer använda makefilen som i sin tur installerar make install och använder sig av phpdoc för att skapa dokumentationen make doc.

Du kan se hur jag jobbar igenom stegen i följande video.

Här är stegen du behöver jobba igenom.

#Installera utvecklingsmiljön

Du kan installera verktyget phpdoc som en del av ditt repo för me/redovisa.

Följande är de make target som du behöver.

# Gå till ditt projekt
$ make help
...
install            - Install all tools
doc                - Generate documentation.
...

Du behöver nu installera verktygen.

make install

#Generera dokumentationen

Nu kan du automatgenerera dokumentationen.

mkdir doc
make doc

Du behöver en katalog som heter doc i ditt projekt, annars genereras inte dokumentationen.

Nu kan du öppna dokumentationen i din webbläsare.

firefox doc

#Konfigurera vad som dokumenteras

När kommandot phpdoc körs av Makefilen så används konfigurationsfilen .phpdoc.xml och den styr vilka kataloger som används som bas för dokumentationen.

Titta i filen och justera vilka kataloger som används som bas, så kan du skapa egen dokumentation för de klasser som installeras via composer.

Du kan till exempel uppdatera din konfigurationsfil så att den även dokumenterar klasserna i Anax, men ignorerar alla klasser som finns under katalogen test/.

<files>
    <directory>src</directory>
    <directory>vendor/anax</directory>
    <ignore>test/*</ignore>
</files>

#Om makefilen

Du använder en av funktionerna som redan finns implementerad i Makefilen. Den installerar verktyget phpdoc i .bin/phpdoc via make install. Sedan kan du generera dokumentationen via make doc, förutsatt att du har en konfigurationsfil samt en katalog doc där dokumentationen kan sparas.

#Krav

1. Använd phpdoc, via make doc för att skapa dokumentation till ditt projekt.

2. Redigera konfigurationsfilen så att du även kan generera dokumentation för Anax moduler.

3. Uppdatera din .gitignore så att du inte checkar in katalogen doc/ in i ditt repo.

4. Bekanta dig med det som genereras av phpdoc och se om du kan finna det användbart.

#Tips från coachen

Lycka till och hojta till i forumet om du behöver hjälp!

#Revision history