Tulipas väännettyä omaan käyttöön sopivampi dokumenttien generoija muiden jo olemassa olevien käytön sijaan, joten jaetaan nyt se muillekin siltä varalta että jollakulla muullakin on tarvetta tai halua käyttää moista PHP-lähdekoodiensa dokumentointiin. Tai jos muuten vain on intoa tutkia toisten kirjoittamia lähdekoodeja.
Elikkäs lyhyesti ja ytimekkäästi tällä hetkellä ainoa tuettu kieli dokumenttien generoijalleni on PHP-lähdekoodit (etsii sanoja public, private, class sekä function) joten C-koodia ei sillä voi dokumentoida eikä monia muitakaan. Kuitenkin itse kerta olen pääosin PHP-koodari ja koska koodasin tämän himmelin omaan käyttööni, ei se itseäni haittaa. Toki en tiedä toimiiko javalla tai muilla sen kaltaisilla. Jos tarvitsee monipuolista työkalua, kannattaa tutustua Doxygeniin.
Eniveis, sivusto löytyy
http://documentgenerator.runosydan.net/ osoitteesta ja ohjelmalla tuotettuja lähdekoodeja voi käydä katsomassa esimerkiksi:
http://s.runosydan.net/nmYi osoitteessa tai vaikkapa
http://s.runosydan.net/36SE osoitteesta. Enemmänkin esimerekkejä löytyy
http://docs.runosydan.net osoitteesta joihinkin luokkiin.
Toiminta lyhyesti web-sivulla: Valitse tiedosto -> lähetä -> saat linkin -> avaa linkki ja katso dokumentaatiot. Näin ainakin ideaalimaailmassa ja omissa lähdekoodeissani jotka aina noudattavat samanlaista kommentointitapaa. Your Mileage May Vary kuten tavataan sanoa, ja jos koodisi on kommentoitu oikealla tavalla eikä silti toimi niin toki voi heittää mailia aleksi.rasanen@runosydan.net osoiteeseen ja antaa bugi-ilmoitusta.
Koodit on kommentoitava Doxygenin tyylillä. Esimerkkejä toimivista dokumentaatiotavoista näet GitHubissa olevista lähdekoodeistani (joista nuo docs.runosydan.net urlissa olevat koodit on haettu ja generoitu pääosiltaan). Eli vaikkapa CFilesystem
https://github.com/stargazers/CFilesystem/blob/master/CFilesystem.php luokka jonka lähdekoodeissa näkyy käytettyä kommentointityyliä.
Lyhyesti idea kommentoinnissa siis on se, että funktion tai metodin yläpuolella olevissa kommenteissa on @brief, @param sekä @return sanoja joista dokumentaatiot generoidaan. Luokan määritelmässä @author, @email, @copyright sekä @license on @briefin lisäksi tuettu.
En tiedä oliko tuo tarpeeksi selkeästi selostettu, mutta saa kysyä jos epäselvää jäi. Ja tosiaan, lähdekoodit eivät jää talteen itselleni tuonne (tiedostot uploadataan, mutta niitä ei siirretä minnekään vaan ne menee /tmp kansiosta pois, ainakin tuolla serverillä näytti katoavan samantien sieltä). Kuitenkin generoidut dokumentaatiot jäävät talteen serverille että ne voi avata myöhemminkin samasta annetusta urlista.
Henkilökohtaisesti itseäni ei kiinosta pätkääkään muiden koodien dokumentaatiot joita en itse koodaa, mutta jos tuntuu epämukavalta ajatukselta että generoidut dokumentaatiot jäävät serverilleni tai jos et luota siihen että koodeja ei tallenneta niin toki kaikki sivuston käyttämät luokat ja koko roskan voi hakea omalle serverilleenkin. Sivusto ja luokat ovat GNU AGPL v3 lisenssin alaisia, joten feel free.
Niin ja tietenkin kysymykseen "Miksi tällainen on olemassa kun Doxygen on olemassa" vastauksena on se, että koska olin liian laiska ja rupesi nyppimään Doxygen-asetustiedoston teko enkä jaksanut paneutua saako sillä generoitua mitenkään dokumentaatiota ilman asetustiedostoa. Ajattelin että pitkässä juoksussa pääsen helpommalla jos koodaan lähdekoodieni kommentoijan omaan kouraani sopivampana jota ei tarvii konfiguroida mitenkään, riittää että koodi on vain kommentoitu oikein. Nyt ajan aina crontabissa tietyssä kansiossa tuota kerran päivässä joten saan automaattisesti lähdekoodeista ajan tasalla olevat dokumentaatiot. Ja sitten tosiaan eilen koodasin vielä tuohon web-käyttöliittymänkin että jos joku muukin haluaa käyttää niin voi testailla + itse voin käyttää jos tarviin yksittäisestä luokasta generoida dokumentaatiot ja jota ei vielä ole tuolla docs.runosydan.net sivustolla.
Että sellaista. Palautetta saa antaa toki yleisesti ottaen myös vaikka sivun visuaalisesta ilmeestä jos se on mielestäsi kamala tai whatever
Aihe: Dokumenttigeneroija PHP-koodeille (Luettu 1928 kertaa)
