{"id":282,"date":"2020-03-04T11:05:24","date_gmt":"2020-03-04T09:05:24","guid":{"rendered":"https:\/\/coursepages.uta.fi\/tiea2-1b\/?page_id=282"},"modified":"2020-03-04T15:09:36","modified_gmt":"2020-03-04T13:09:36","slug":"javadoc-ohjeet","status":"publish","type":"page","link":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/kevat-2020\/harjoitustyo\/javadoc-ohjeet\/","title":{"rendered":"Javadoc-ohjeet"},"content":{"rendered":"<p>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<p>Alla annetaan lyhyet ohjeet html-muotoisen dokumentoinnin generointiin l\u00e4hdekodista ja sen Javadoc-kommenteista ja esimerkkej\u00e4.<\/p>\n<p>Huomioitavaa:<\/p>\n<ul>\n<li>Pelk\u00e4t Javadoc-kommentit eiv\u00e4t riit\u00e4! Metodien sis\u00e4lt\u00e4 pit\u00e4\u00e4 l\u00f6yty\u00e4 &#8221;tavallisia&#8221; kommentteja.<\/li>\n<li>Javadoc-ohjelma on hyvin monipuolinen ty\u00f6kalu, jolla voi halutessaan tehd\u00e4 hienompiakin dokumentaatioita, mutta alla olevilla ohjeilla saa aikaiseksi harjoitusty\u00f6n tarkastajille mainiosti kelpaavat tiedostot.<\/li>\n<\/ul>\n<h3>Javadoc-kommenttien kirjoittaminen<\/h3>\n<p>Javadoc-ohjelma muodostaa dokumentit \/** *\/ -muotoisten kommenttien sis\u00e4\u00e4n kirjoitetusta tekstist\u00e4.<\/p>\n<pre>\/** T\u00e4m\u00e4 on Javadoc-kommentti. Alussa on kaksi asteriskia \r\nja lopussa yksi asteriski. *\/<\/pre>\n<pre>\/* T\u00e4m\u00e4 on tavallinen kommentti. Alussa ja lopussa yksi asteriski. *\/<\/pre>\n<p>Moniriviset kommentit kirjoitetaan yleens\u00e4 lis\u00e4ten asteriski kommentin kunkin rivin alkuun n\u00e4in:<\/p>\n<pre>\/**\r\n * Abstrakti Otus-luokka, joka sis\u00e4lt\u00e4\u00e4 otuksille\r\n * yhteiset piirteet.\r\n * &lt;p&gt;\r\n * Harjoitusty\u00f6, Olio-ohjelmoinnin perusteet I, kev\u00e4t 201x.\r\n * &lt;p&gt;\r\n * @author Jorma Laurikkala (jorma.laurikkala@tuni.fi),\r\n * Informaatioteknologian ja viestinn\u00e4n tiedekunta,\r\n * Tampereen yliopisto.\r\n *\/<\/pre>\n<p>Kommentin on sijaittava v\u00e4litt\u00f6m\u00e4sti ennen dokumentoitavaa kohdetta.<\/p>\n<p><strong><span style=\"color: red\">V\u00e4\u00e4rin<\/span><\/strong> \u2013 <strong>import<\/strong>-lause est\u00e4\u00e4 luokkakuvauksen muodostamisen:<\/p>\n<pre>\/**\r\n * Abstrakti Otus-luokka, joka sis\u00e4lt\u00e4\u00e4 otuksille\r\n * yhteiset piirteet.\r\n * &lt;p&gt;\r\n * Harjoitusty\u00f6, Olio-ohjelmoinnin perusteet I, kev\u00e4t 201x.\r\n * &lt;p&gt;\r\n * @author Jorma Laurikkala (jorma.laurikkala@tuni.fi),\r\n * Informaatioteknologian ja viestinn\u00e4n tiedekunta,\r\n * Tampereen yliopisto.\r\n *\/<\/pre>\n<pre>import java.util.Random;\r\n\r\npublic abstract class Otus {\r\n   ...\r\n}<\/pre>\n<p><strong><span style=\"color: green\">Oikein<\/span><\/strong> \u2013 kommentti v\u00e4litt\u00f6m\u00e4sti ennen luokan m\u00e4\u00e4rittely\u00e4:<\/p>\n<pre>import java.util.Random;<\/pre>\n<pre>\/**\r\n * Abstrakti Otus-luokka, joka sis\u00e4lt\u00e4\u00e4 otuksille yhteiset piirteet.\r\n * &lt;p&gt;\r\n * Harjoitusty\u00f6, Olio-ohjelmoinnin perusteet I, kev\u00e4t 201x.\r\n * &lt;p&gt;\r\n * @author Jorma Laurikkala (jorma.laurikkala@tuni.fi),\r\n * Informaatioteknologian ja viestinn\u00e4n tiedekunta,\r\n * Tampereen yliopisto.\r\n *\/\r\n\r\npublic abstract class Otus {\r\n   ...\r\n}<\/pre>\n<p>Luokkakohtaisista kommenteista tulee l\u00f6yty\u00e4 harjoitusty\u00f6n tekij\u00e4n nimi <strong>@author<\/strong>-m\u00e4\u00e4reell\u00e4 annettuina (katso yll\u00e4).<\/p>\n<p>Metodien ja attribuuttien kuvaukset kirjoitetaan luokkakuvauksen tavoin juuri ennen kohdettaan:<\/p>\n<pre>\/** Otuksen yksik\u00e4sitteinen tunnus. *\/\r\nprivate long tunnus;\r\n...\r\n\r\n\/** \r\n * Taistellaan toisen otuksen kanssa.\r\n *\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>\n<p>Metodikuvauksissa kerrotaan lyhyesti mit\u00e4 metodi tekee sek\u00e4 m\u00e4\u00e4ritell\u00e4\u00e4n tarvittaessa parametrit ja paluuarvo. Parametri kuvataan <strong>@param<\/strong>-m\u00e4\u00e4reell\u00e4 siten, ett\u00e4 m\u00e4\u00e4reen per\u00e4\u00e4n kirjoitetaan parametrin nimi ja nimen j\u00e4lkeen parametrin kuvaus. Nimi erotetaan kuvauksesta yhdell\u00e4 v\u00e4lily\u00f6nnill\u00e4. Et voi k\u00e4ytt\u00e4\u00e4 erottimena esimerkiksi pilkkua. Paluuarvon m\u00e4\u00e4rittely tehd\u00e4\u00e4n <strong>@return<\/strong>-m\u00e4\u00e4reell\u00e4. Metodin heitt\u00e4m\u00e4t poikkeukset annetaan <strong>@throws<\/strong>-m\u00e4\u00e4reen avulla.<\/p>\n<p>Javadoc-kommentit on kirjoitettava my\u00f6s yksityisille (<strong>private<\/strong>) luokan piirteille.<\/p>\n<p>Javadoc-kommentien ja kommenttien kohteen v\u00e4liss\u00e4 olevat tavalliset kommentit esimerkiksi alla annetulla tavalla:<\/p>\n<pre>\/** Otuksen yksik\u00e4sitteinen tunnus. *\/\r\n\/\/ Muista tavanomaista suurempi tyyppi!\r\nprivate long tunnus;\r\n<\/pre>\n<p>eiv\u00e4t haittaa dokumentaation muodostamista, mutta yleens\u00e4 kohteen Javadoc-kommentteja k\u00e4ytett\u00e4ess\u00e4 kommentteja ei t\u00e4ydennet\u00e4 tavallisilla kommenteilla.<\/p>\n<p>Abstraktien metodien Javadoc-kommentit &#8221;perityv\u00e4t&#8221; korvattujen metodien Javadoc-kommenteiksi automaattisesti ilman lis\u00e4toimia.<\/p>\n<h3>Javadoc-kommenttien muodostaminen<\/h3>\n<p>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 <strong>javadoc<\/strong>. Javadoc-ohjelma sijaitsee JDK:n <em>bin<\/em>-alihakemistossa. Polku voi olla Windows-k\u00e4ytt\u00f6j\u00e4rjestelm\u00e4ss\u00e4 esimerkiksi <em>C:\\Program Files (x86)\\Java\\jdk1.8.0\\bin\\javadoc.exe<\/em>.<\/p>\n<p>NetBeansin tapaiset kehitysv\u00e4lineet kutsuvat Javadoc-ohjelmaa itse, jolloin k\u00e4ytt\u00e4j\u00e4n ei tarvitse suorittaa ohjelmaa komentoikkunassa.<\/p>\n<p>Javadoc-ohjelmaa on paras kutsua &#8221;ty\u00f6hakemistostosta&#8221;, jonka v\u00e4litt\u00f6m\u00e4n\u00e4 alihakemistona on <em>harjoitustyo<\/em>-pakkausten hakemisto. T\u00e4m\u00e4 on sama hakemisto, josta ohjelman k\u00e4\u00e4nt\u00e4minen ja suorittaminen on sujuvinta komentoikkunassa.<\/p>\n<p>Javadoc-ohjelmaa k\u00e4ytett\u00e4ess\u00e4 on t\u00e4rke\u00e4\u00e4 m\u00e4\u00e4ritell\u00e4 hakemisto, jonne sen luomat tiedostot tallennetaan, koska Javadoc sijoittaa oletusarvoisesti kaikki tuottamansa tiedostot hakemistoon, josta ohjelmaa kutsutaan. Ilman hakemistoa projektin hakemistoon tulee pahimmillaan kymmeni\u00e4 tiedostoja ja hakemistoja, joiden poistaminen vie aikaa ja vaatii tarkkuutta. Hakemiston m\u00e4\u00e4rittelyss\u00e4 on huomattava, ett\u00e4 <span style=\"background-color: #ffff99\">Javadoc-tiedostoja ei saisi pit\u00e4\u00e4 versionhallinnassa, koska ne voi tavukoodin tapaan muodostaa aina tarvittaessa l\u00e4hdekoodista<\/span>.<\/p>\n<p>Javadoc-ohjelmaa kutsutaan komennolla:<\/p>\n<pre>javadoc -d ..\\javadocs -private -author -noqualifier all -subpackages harjoitustyo -encoding utf8\r\n<\/pre>\n<ul>\n<li><strong>d<\/strong>: dokumentaatio sijoitetaan omaan hakemistoon.Yll\u00e4 Javadoc-ohjelmaa k\u00e4sket\u00e4\u00e4n sijoittamaan tiedostonsa ylihakemistossa olevaan alihakemistoon (..\\<em>javadocs<\/em>), jotta Javadoc-dokumentaatio ei j\u00e4isi versionhallinnan piiriss\u00e4 olevaan hakemistoon. Huomaa Windowsin tiedostonerotin. Linux- ja Mac-j\u00e4rjestelmiss\u00e4 sanottaisiin ..\/<em>javadocs<\/em>. <strong><br \/>\n<\/strong><\/li>\n<li><strong>private<\/strong>: huomioi piirteiden Javadoc-kommentit n\u00e4kyvyysm\u00e4\u00e4reist\u00e4 riippumatta.<\/li>\n<li><strong>author<\/strong>: sis\u00e4llytt\u00e4\u00e4 <strong>@author<\/strong>-m\u00e4\u00e4reen dokumentaatioon.<\/li>\n<li><strong>noqualifier<\/strong>: j\u00e4tt\u00e4\u00e4 paramerilla <em>all<\/em> pakkauksen nimen pois kaikkien luokkien nimist\u00e4.<\/li>\n<li><strong>subpackages<\/strong>: generoi dokumentaation annetuille pakkauksille. Yll\u00e4 parametrina <em>harjoitustyo<\/em>.<\/li>\n<\/ul>\n<p>Komennon tuloksena <em>javadocs<\/em>-hakemistoon pit\u00e4isi synty\u00e4 Javadoc-dokumentaatio eli joukko html-muotoisia tiedostoja, joita luetaan <em>index.html<\/em>-tiedoston kautta.<\/p>\n<p>Voit kohdata merkist\u00f6ongelmia 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.<\/p>\n<p>Edellisess\u00e4 komennossa oli lis\u00e4parametrina:<\/p>\n<ul>\n<li><strong>encoding<\/strong>: l\u00e4hdekoodin merkist\u00f6. Yll\u00e4 parametrina <em>utf8<\/em>.<strong><br \/>\n<\/strong><\/li>\n<\/ul>\n<p>jotta Windows-j\u00e4rjestelm\u00e4ss\u00e4 voitiin generoida dokumentaatio utf-8-merkist\u00f6isest\u00e4 l\u00e4hdekoodista. Mac- tai Linux-j\u00e4rjestelmiss\u00e4 t\u00e4t\u00e4 parametria ei pit\u00e4isi tarvita.<\/p>\n<p>Merkist\u00f6j\u00e4 voi tarvittaessa s\u00e4\u00e4t\u00e4\u00e4 lis\u00e4\u00e4 parametreilla:<\/p>\n<ul>\n<li><strong>docencoding<\/strong>: dokumentaation merkist\u00f6.<\/li>\n<li><strong>charset<\/strong>: asettaa erikseen html-dokumentin <em>meta<\/em>-elementin <em>charset<\/em>-attribuutin arvon.<\/li>\n<\/ul>\n<p>Yll\u00e4 tiedostot ohjattiin versionhallinnan ulkopuolella olevaan hakemistoon. Toinen tapa v\u00e4ltt\u00e4\u00e4 Javadoc-dokumentaation joutuminen versionhallintaan on <em>.gitignore<\/em>-tiedosto, johon voi m\u00e4\u00e4ritell\u00e4 my\u00f6s hakemistoja.<\/p>\n<h3>Linkit<\/h3>\n<p><a href=\"http:\/\/www.oracle.com\/technetwork\/java\/javase\/documentation\/index-137868.html\" target=\"_top\">How to Write Doc Comments for Javadoc<\/a><\/p>\n<p><a href=\"http:\/\/www.oracle.com\/technetwork\/java\/javase\/documentation\/index-jsp-135444.html\" target=\"_top\"> Javadoc Tool Home Page<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 l\u00e4hdekodista ja sen Javadoc-kommenteista ja esimerkkej\u00e4. Huomioitavaa: Pelk\u00e4t Javadoc-kommentit eiv\u00e4t riit\u00e4! Metodien sis\u00e4lt\u00e4 &hellip; <a href=\"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/kevat-2020\/harjoitustyo\/javadoc-ohjeet\/\" class=\"more-link\">Jatka artikkeliin <span class=\"screen-reader-text\">Javadoc-ohjeet<\/span><\/a><\/p>\n","protected":false},"author":6,"featured_media":0,"parent":278,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-282","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/pages\/282","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/comments?post=282"}],"version-history":[{"count":8,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/pages\/282\/revisions"}],"predecessor-version":[{"id":301,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/pages\/282\/revisions\/301"}],"up":[{"embeddable":true,"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/pages\/278"}],"wp:attachment":[{"href":"https:\/\/coursepages2.tuni.fi\/tiea2-1b\/wp-json\/wp\/v2\/media?parent=282"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}