⌛⌛ JSON & Javadoc¶

Huomaa!

Edellisessä tehtävässä luotiin uusia haaroja tietovarastoon. Varmista, että olet main-haarassa ennen kuin tallennat tämän tehtävän tiedostoja paikalliseen tietovarastoosi.

Huomaa!

Pakkauksen nimen olisi järkevämpää olla fi.tuni.prog3.javadocjson. (Tehtävässä oli edellisellä kurssitoteutuksella epäloogisempi fi.tuni.prog3.json, joka jäi epähuomiossa päivittämättä.) Pakkauksen nimen voi säätää NetBeansissa tehtävässä määritellyksi muuttamalla NetBeansin ehdottaman pakkausnimen viimeinen osan nimestä json nimeksi javadocjson. Huomaa, että tämä on epästandardi tapa nimetä Maven-projektin pakkaus. Mavenissa on vakiintunut käytäntö on se, että pakkauksen nimi päättyy projektin nimeen. Pakkauksen nimen muutto on demottu 10.3. pidetyllä englanninkielisellä kyselytunnilla. Videossa on kirjanmerkki demoon.

Seuraavaksi kokeillaan pakkauksen sisältämien luokkien dokumentointia Javadoc-työkalulla. Tehtävän pohjana käytetään aiemman JSON-tehtävän luokkia Node, ArrayNode, ObjectNode ja ValueNode lähes sellaisenaan.

Palautus koostuu Maven-projektista.

Tehtäväsi on organisoida ja muokata luokat Node, ArrayNode, ObjectNode ja ValueNode sellaisiksi, että Javan Javadoc-työkalu luo niiden pohjalta samanlaisen dokumentaation kuin materiaalien etätietovaraston round10\javadocjson\apidocs-hakemistossa on annettu mallidokumentaatio.

Järjestä funktiot luokkiisi samaan järjestykseen kuin ne ovat esimerkkidokumentaatiossa.

Älä luo tai kommentoi package-info.java tiedostoa.

Tässä tulee siis toisaalta lisätä asianmukaiset Javadoc-kommentit ja toisaalta huomata, että mallidokumentaatio edellyttää luokkiin pieniä muutoksia verrattuna aiempaan JSON-tehtävään.

Luokat on määritetty kuulumaan pakkaukseen fi.tuni.prog3.json, jolloin tiedostojesi tulee olla round10\javadocjson\src\main\java\fi\tuni\prog3\json-hakemistossa.
Luokille Node, ArrayNode ja ObjectNode on tehty rakentajat, jotta niille voidaan määrittää Javadoc-kommentit.
Osa jäsenfunktioista heittää poikkeuksen.

Tässä tehtävässä ei testata luokkien toiminnallisuutta sinänsä, mutta koodin tulee kääntyä. Sijoita JsonTest.java-tiedosto round10\javadocjson\src\main\java-hakemistoon, jos haluat ajaa Maven-projektisi testiluokkaa käyttäen.

Testauksesta¶

Tarkistin pyrkii tutkimaan, että palauttamistasi kooditiedostoista generoitu Javadoc-dokumentaatio vastaa annettua mallidokumentaatiota. Tarkistus koskee tarkemmin ottaen materiaalien etävaraston hakemistossa round10\javadocjson\apidocs\fi\tuni\prog3\json olevia HTML-tiedostoja, joita voit tarkastella selaimella ja joihin voit verrata koodistasi tuotettua dokumentaatiota.

Tarkistuksen mahdollisen hyvän onnistumisen kannalta on suositeltavaa, että kopioit Javadoc-kommenttien tekstit sellaisenaan mallidokumentaatiosta, vaikka automaattitarkistin ei odota mallikommenttien ja omien kommenttiesi olevan sanasta sanaan samat. Varmista, että funktiot ovat kommentoimissasi luokissa samassa järjestyksessä kuin esimerkkidokumentaatiossa.

Tarkistin kääntää koodisi Mavenilla komennolla mvn package sekä generoi siitä Javadoc-dokumentaation. Projektisi pom.xml-tiedoston sisällöllä ei ole tämän suhteen merkitystä, sillä tarkistin käyttää käännöksessä omaa projektitiedostoaan.

Sinun ei ole tehtävää tehdessäsi pakko käyttää Mavenia dokumentaation luomiseen, koska voit kutsua Javan mukana tulevaa Javadoc-ohjelmaa itse ilman Mavenin apua esimerkiksi komennolla javadoc -d myapidocs -sourcepath src/main/java fi.tuni.prog3.json, jolloin tehtävän kannalta oleelliset HTML-tiedostot sijoitetaan round10\javadocjson\myapidocs\fi\tuni\prog3\json-hakemistoon. Yllä oletetaan, että komento annetaan projektin juurihakemistossa round10\javadocjson\src.

A+ esittää tässä kohdassa tehtävän palautuslomakkeen.