Najlakši put do relativno kvalitetne i sveže dokumentacije je korišćenjem pravilno formatiranih komentara unutar samog koda. Dokumentacija može biti up-to-date bez mnogo cimanja samo uz malo discipline pošto je uvek programeru pred očima i lako ju je lako održavati.
Primer jednog takvog inline komenatara za PHP:
/** * Check if specific page is first page * * @param integer $page Page that need to be checked. If * value of this param is NULL current page will be used * @return boolean */ function isFirst($page = null) { $page = is_null($page) ? $this->getCurrentPage() : (integer) $page; return $page == 1; } // isFirst
Jednostavno. Sve ide samo od sebe kad se nauči par pravila i stekne navika pisanja ovakvih kometnara (ako koristite neki napredniji editor koji podržava code template onda editor može da odradi skoro sav dosadan posao za vas).
Ovako spremljena dokumentacija se pomoću specijalizovanih alata lako prebacuje u čitam i ulinkovan oblik. Standardan alat za izvlačenje dokumentacije iz PHP koda je phpDocumentor, a ako vas zanima kako izgleda generisana dokumentacija na ovoj stranici imate gomile linkova ka dokumentcijama "živih" PHP projekata koje su generisanje pomoću ovog alata.
Sve je to jako lepo, ali meni smeta par stvari. Prva i osnovna je što uz phpDocumentor ne dolazi ni jedan set templatea za koji se može reći da je dovoljno jednostavan i čitak da bi ljudi stvarno čitali generisanu dokumentaciju. Sve mi deluje previše nabacano, a developeri kao da su se trudili da akcentuju nebitne stvari. Dokumentacija je maksimalno nepregledna, prostor loše iskorišćen, a podaci koji su prikazani su u prevelikom broju slučajeva jednostavno nebitni i smetaju čoveku da dođe do stvarno vrednih informacija.
Primer čitke i pregledne API dokumentacije izvučene iz koda možete videti kod Rails API dokumetnacije. Vidi se da je u istu uloženo dosta truda, a sam layout dokumentacije je dovoljno pregledan (ako izuzetmo gomile frameova sa strane, to je moglo mnogo lepše da se reši).
No dobro, na svu sreću phpDocumentor podržava definisanje custom seta template (opet malo nesrećan način definisanja tempaltea) tako da ću najverovatnije sesti i napraviti sopstvene kad bude bilo potrebe da generisane dokumentacije i javno pokažem.
