Kaikki itse tehdyt harjoitusty\u00f6n luokat dokumentoidaan Javadoc-ohjelmalla.Kaikille attribuuteille \u2013 niin tavallisille kuin vakioiduille \u2013 tulee kirjoittaa Javadoc-kommentit. L\u00e4hes kaikki metodit Javadoc-kommentoidaan. Mik\u00e4li aksessoreissa ja rakentajissa ei tehd\u00e4 mit\u00e4\u00e4n erityist\u00e4, niin n\u00e4it\u00e4 metodeja ei tarvitse kommentoida.<\/p>\n
Alla annetaan lyhyet ohjeet HTML-muotoisen dokumentoinnin generointiin ja esimerkkej\u00e4.<\/p>\n
Huomioitavaa:<\/p>\n
Javadoc-ohjelma muodostaa dokumentit \/** *\/ -muotoisten kommenttien sis\u00e4\u00e4n kirjoitetusta tekstist\u00e4.<\/p>\n
\/** T\u00e4m\u00e4 on Javadoc-kommentti. Alussa on kaksi asteriskia \r\nja lopussa yksi asteriski. *\/<\/pre>\n\/* T\u00e4m\u00e4 on tavallinen kommentti. Alussa ja lopussa yksi asteriski. *\/<\/pre>\nKommentin on sijaittava v\u00e4litt\u00f6m\u00e4sti ennen dokumentoitavaa kohdetta.<\/p>\n
V\u00e4\u00e4rin<\/span><\/strong>\u00a0\u2013 import<\/strong>-lause est\u00e4\u00e4 luokkakuvauksen muodostamisen:<\/p>\n
\/**\r\n * Abstrakti Otus-luokka, joka sis\u00e4lt\u00e4\u00e4 otuksille\r\n * yhteiset piirteet.\r\n * <p>\r\n * Harjoitusty\u00f6, Olio-ohjelmoinnin perusteet, kev\u00e4t 2010.\r\n * <p>\r\n * @author Jorma Laurikkala (jorma.laurikkala@uta.fi),\r\n * Luonnontieteiden tiedekunta, Tampereen yliopisto.\r\n *\/<\/pre>\nimport java.util.Random;\r\n\r\npublic abstract class Otus {\r\n ...\r\n}<\/pre>\nOikein<\/span><\/strong>\u00a0\u2013 kommentti v\u00e4litt\u00f6m\u00e4sti ennen luokan m\u00e4\u00e4rittely\u00e4:<\/p>\n
import java.util.Random;<\/pre>\n\/**\r\n * Abstrakti Otus-luokka, joka sis\u00e4lt\u00e4\u00e4 otuksille\r\n * yhteiset piirteet.\r\n * <p>\r\n * Harjoitusty\u00f6, Olio-ohjelmoinnin perusteet, kev\u00e4t 2010.\r\n * <p>\r\n * @author Jorma Laurikkala (jorma.laurikkala@uta.fi),\r\n * Luonnontieteiden tiedekunta, Tampereen yliopisto.\r\n *\/\r\n\r\npublic abstract class Otus {\r\n ...\r\n}<\/pre>\nLuokkakohtaisista kommenteista tulee l\u00f6yty\u00e4 harjoitusty\u00f6n tekij\u00e4n nimi @author<\/strong>-m\u00e4\u00e4reell\u00e4 annettuina (katso yll\u00e4).<\/p>\n
Metodien ja attribuuttien kuvaukset kirjoitetaan luokkakuvauksen tavoin juuri ennen kohdettaan:<\/p>\n
\/** Otuksen yksik\u00e4sitteinen tunnus. *\/\r\nprivate long tunnus;\r\n...\r\n\r\n\/** Taistellaan toisen otuksen kanssa.\r\n * Voitto p\u00e4\u00e4tell\u00e4\u00e4n vertailemalla uusia terveydentiloja.\r\n *\r\n * @param toinen vastustaja toisesta joukkueesta.\r\n * @param punainen onko vastustaja punaisesta joukkueesta?\r\n * @return 1, jos tuli voitto, 0, jos tuli tasapeli ja -1,\r\n * jos toinen voitti.\r\n * @throws IllegalArgumentException jos parametreissa oli virhe.\r\n *\/\r\npublic int taistele(Otus toinen, boolean punainen)\r\nthrows IllegalArgumentException {\r\n ...\r\n}\r\n<\/pre>\nMetodikuvauksissa kerrotaan lyhyesti mit\u00e4 metodi tekee sek\u00e4 m\u00e4\u00e4ritell\u00e4\u00e4n tarvittaessa parametrit ja paluuarvo. Parametri kuvataan @param<\/strong>-m\u00e4\u00e4reell\u00e4 siten, ett\u00e4 m\u00e4\u00e4reen per\u00e4\u00e4n kirjoitetaan parametrin nimi ja nimen j\u00e4lkeen parametrin kuvaus. Paluuarvon m\u00e4\u00e4rittely tehd\u00e4\u00e4n @return<\/strong>-m\u00e4\u00e4reell\u00e4. Metodin heitt\u00e4m\u00e4t poikkeukset annetaan @throws<\/strong>-m\u00e4\u00e4reen avulla.<\/p>\n
Javadoc-kommentit on kirjoitettava my\u00f6s yksityisille (private<\/strong>) luokan piirteille.<\/p>\n
Solmu<\/em>– ja LinkitettyLista<\/em>-luokat sek\u00e4 AbstraktiLista<\/em>-yliluokka ja Lista<\/em>-rajapinta on dokumentoitu esimerkinomaisesti. Harjoitusty\u00f6ss\u00e4 tulisi siis olla suunnilleen samantasoinen Javadoc-dokumentaatio kuin edell\u00e4 mainituissa luokissa ja rajapinnassa. Huomaa, ett\u00e4 LinkitettyLista<\/em>– ja AbstraktiLista<\/em>-luokissa osa kommenteista on ”periytetty” @inheritDoc<\/strong>-m\u00e4\u00e4reell\u00e4 Lista<\/em>-rajapinnasta, jotta samoja kommentteja ei ole tarvinnut kirjoittaa uudelleen n\u00e4ihin luokkiin. Korvattujen metodien Javadoc-kommentit kopioituvat my\u00f6s ilman lis\u00e4toimia, mutta @inheritDoc<\/strong>-m\u00e4\u00e4reell\u00e4 kommentteja voi tarvittaessa tarkentaa.<\/p>\n
Javadoc-kommenttien muodostaminen<\/h3>\n
Javadoc-ohjelma tulee aina Java JDK -paketin mukana. Se ei ole saatavilla erikseen. Mik\u00e4li polkum\u00e4\u00e4rittelyt ovat kunnossa, on Javadoc-ohjelma on ajettavissa komentorivilt\u00e4 suoraan komennolla javadoc<\/strong>. Javadoc-ohjelma sijaitsee JDK-paketin bin<\/em>-alihakemistossa. Polku voi olla Windows-k\u00e4ytt\u00f6j\u00e4rjestelm\u00e4ss\u00e4 esimerkiksi C:\\Program Files (x86)\\Java\\jdk1.8.0\\bin\\javadoc.exe<\/em>.<\/p>\n
NetBeansin tapaiset kehitysv\u00e4lineet kutsuvat Javadoc-ohjelmaa itse, jolloin k\u00e4ytt\u00e4j\u00e4n ei tarvitse suorittaa ohjelmaa komentoikkunassa.<\/p>\n
Javadoc-ohjelmaa on paras kutsua hakemistossa, jossa on ajoluokka Oope2081HT<\/em> ja jonka v\u00e4litt\u00f6m\u00e4n\u00e4 alihakemistona on oope2018ht<\/em>-pakkausten hakemisto. T\u00e4m\u00e4 on sama hakemisto, josta ohjelman k\u00e4\u00e4nt\u00e4minen ja suorittaminen on sujuvinta komentoikkunassa.<\/p>\n
Javadoc-ohjelmaa kutsutaan komennolla:<\/p>\n
javadoc Oope2018HT.java -d javadocs -private -author -noqualifier all -subpackages oope2018ht<\/pre>\nOhjelman parametrit m\u00e4\u00e4rittelev\u00e4t seuraavaa:
\n<\/strong><\/p>\n\n
- d<\/strong>: dokumentaatio sijoitetaan omaan hakemistoon. Yll\u00e4 parametrina javadoc<\/em>.
\n<\/strong><\/li>\n- private<\/strong>: huomioi piirteiden Javadoc-kommentit n\u00e4kyvyysm\u00e4\u00e4reist\u00e4 riippumatta.<\/li>\n
- author<\/strong>: sis\u00e4llytt\u00e4\u00e4 @author<\/strong>-m\u00e4\u00e4reen dokumentaatioon.<\/li>\n
- noqualifier<\/strong>: j\u00e4tt\u00e4\u00e4 paramerilla all<\/em> pakkauksen nimen pois kaikkien luokkien nimist\u00e4.<\/li>\n
- subpackages<\/strong>: generoi dokumentaation annetuille pakkauksille. Yll\u00e4 parametrina oope2018ht<\/em>.<\/li>\n<\/ul>\n
S\u00e4\u00e4d\u00e4 tarvittaessa NetBeansin tai vastaavan kehitysohjelman asetuksia siten, ett\u00e4 kommentit muodostuvat yll\u00e4 m\u00e4\u00e4ritellyll\u00e4 tavalla.<\/p>\n
Komennon tuloksena javadocs<\/em>-hakemistoon pit\u00e4isi synty\u00e4 Javadoc-dokumentaatio eli joukko HTML-muotoisia tiedostoja, joita luetaan index.html<\/em>-tiedoston kautta.<\/p>\n
Voit kohdata merkist\u00f6ongelmia my\u00f6s Javadoc-ohjelmaa k\u00e4ytt\u00e4ess\u00e4si. Javadoc k\u00e4ytt\u00e4\u00e4 k\u00e4ytt\u00f6j\u00e4rjestelm\u00e4n oletusmerkist\u00f6\u00e4, joka on Windowsissa usein Windows-1252 ja Mac- ja Linux-j\u00e4rjestelmiss\u00e4 tyypillisesti UTF-8-koodattu Unicode-merkist\u00f6. Tilanteesta riippuen dokumentaation luominen ep\u00e4onnistuu tai osa kommenttien merkeist\u00e4 n\u00e4kyy dokumenteista v\u00e4\u00e4rin, kun kommentit luodaan l\u00e4hdekoodista, jonka merkist\u00f6 poikkeaa j\u00e4rjestelm\u00e4n merkist\u00f6st\u00e4. Vain yhdess\u00e4 j\u00e4rjestelm\u00e4ss\u00e4 ty\u00f6skennelt\u00e4ess\u00e4 merkist\u00f6ongelma selvi\u00e4\u00e4 helpoiten vaihtamalla v\u00e4\u00e4r\u00e4ss\u00e4 merkist\u00f6ss\u00e4 olevan koodin merkist\u00f6 j\u00e4rjestelm\u00e4n merkist\u00f6ksi. Esimerkiksi Windowsissa vahingossa UTF-8-merkist\u00f6ll\u00e4 tehty tiedosto on helppo muuttaa esimerkiksi Notepad++-editorilla<\/a> Windowsin merkist\u00f6\u00f6n.<\/p>\n
Eri j\u00e4rjestelmi\u00e4 k\u00e4ytett\u00e4ess\u00e4 Javadoc-ohjelma t\u00e4ytyy ohjata parametrien avulla oikean merkist\u00f6n pariin. Esimerkiksi Windows-j\u00e4rjestelm\u00e4ss\u00e4 voi tuottaa UTF-8-merkist\u00f6isest\u00e4 l\u00e4hdekoodista UTF-8-merkist\u00f6isen dokumentaation komennolla:<\/p>\n
javadoc Oope2018HT.java -d javadocs -private -author -noqualifier all -subpackages oope2018ht -encoding utf8 -docencoding utf8 -charset utf8<\/pre>\nOhjelman parametrit m\u00e4\u00e4rittelev\u00e4t seuraavaa:
\n<\/strong><\/p>\n\n
- encoding<\/strong>: l\u00e4hdekoodin merkist\u00f6. Yll\u00e4 parametrina utf8<\/em>.
\n<\/strong><\/li>\n- docencoding<\/strong>: dokumentaation merkist\u00f6. Yll\u00e4 parametrina utf8<\/em>.<\/li>\n
- charset<\/strong>: asettaa HTML-dokumentin meta<\/em>-elementin charset<\/em>-attribuutin arvon. T\u00e4m\u00e4 attribuutti kertoo selaimelle miss\u00e4 merkist\u00f6ss\u00e4 dokumentti on. Yll\u00e4 parametrina utf8<\/em>.<\/li>\n<\/ul>\n
Linkit<\/h3>\n
Solmu<\/em>-, LinkitettyLista<\/em> ja AbstraktiLista<\/em>-luokista ja Lista<\/em>-rajapinnasta generoitu dokumentaatio<\/a>.<\/p>\n
How to Write Doc Comments for Javadoc<\/a><\/p>\n
Javadoc Tool Home Page<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Kaikki itse tehdyt harjoitusty\u00f6n luokat dokumentoidaan Javadoc-ohjelmalla.Kaikille attribuuteille \u2013 niin tavallisille kuin vakioiduille \u2013 tulee kirjoittaa Javadoc-kommentit. L\u00e4hes kaikki metodit Javadoc-kommentoidaan. Mik\u00e4li aksessoreissa ja rakentajissa ei tehd\u00e4 mit\u00e4\u00e4n erityist\u00e4, niin n\u00e4it\u00e4 metodeja ei tarvitse kommentoida. Alla annetaan lyhyet ohjeet HTML-muotoisen dokumentoinnin generointiin ja esimerkkej\u00e4. Huomioitavaa: Pelk\u00e4t Javadoc-kommentit eiv\u00e4t riit\u00e4! Koodista pit\u00e4\u00e4 l\u00f6yty\u00e4 ”tavallisia” kommentteja. Javadoc-ohjelma … Jatka artikkeliin Javadoc-ohjeet<\/span><\/a><\/p>\n","protected":false},"author":6,"featured_media":0,"parent":255,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-348","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/pages\/348","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/comments?post=348"}],"version-history":[{"count":16,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/pages\/348\/revisions"}],"predecessor-version":[{"id":364,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/pages\/348\/revisions\/364"}],"up":[{"embeddable":true,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/pages\/255"}],"wp:attachment":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1\/wp-json\/wp\/v2\/media?parent=348"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}