Koodiprojekti

En oo vielä päättänyt pitäisikö käyttää automaattista dokumentointia vai ei, joten en veilä speksannut tota osiota. Onks jollain kokemuksia ko. työkaluista ? Eikö ne tee kommenteista hieman epäselviä ?

alkuun kirjoitti:

En oo vielä päättänyt pitäisikö käyttää automaattista dokumentointia vai ei, joten en veilä speksannut tota osiota. Onks jollain kokemuksia ko. työkaluista ? Eikö ne tee kommenteista hieman epäselviä ?

Lue lisää

Kieltämäti joitain dokumentointityökaluja varten tehdyt koodien kommentit ovat hieman epäselviä - varsinkin sellaiset jotka sisältävät erikoisempia html -muotoiluja. Tietysti sellaisille, jotka tietävät mitä merkinnät suunnilleen tarkoittavat, lukeminen ei tuota suuria ongelmia.
Riippuu paljolti minkälaisen lopputuloksen haluat lopputulokseksi työkalulta. Jos ajatellaan, että jokainen luokkamäärittely olisi omana tiedostonaan, ja riittäisi että työkalu osaisi poimia html-tiedostoihin (yksi per tiedosto):
- tiedoston otsikon ja muutaman seliterivin
- ei osaisi poimia jäsenfunktioiden/muuttujien kommentteja
niin työkalu ei tarvitsisi olla ihmeellinen tai lähdekoodin kommenttien vaikeaselkoisia.
Itse olen käytellyt muutamassa projektissa erästä kaupallista työkalua, jolla tulee hierarkiapuu ja kohtalainen seloste melko pienellä vaivalla, mutta kannattaa ensin katsella minkälaista lopputulosta kukin ohjelma tuottaa ja minkälaisella kirjoittelulla. Tietty pitää huomioida viitsiikö koodatessa mietiskellä ohjelman hienouksia kuten:
\f[
\left\{
u(a,t)-
\int_{\gamma(t)}^a
\frac{d\theta}{k(\theta,t)}
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
\right\} dt
\f]
Ainakin työkaluvaihtoehtoja on tusina ilmaista ja vähintään toinen kaupallisia eli valinanvaraa on.