Groovydoc otettiin käyttöön vuonna 2007 tarjoamaan Groovylle mitä Javadoc tarjoaa Javalle. Groovydocia käytetään API-dokumentaation luomiseen Groovy- ja Java-luokille, jotka muodostavat Groovy-kielen. Tässä viestissä tarkastelen Groovydocin käynnistämistä komentorivin ja Groovyn tarjoaman mukautetun Ant-tehtävän kautta.
Groovy- ja Java-lähdekoodit Groovydoc / Javadoc -kommenteilla
Käytän Groovy-käsikirjoituksen mukautettuja versioita ja luokkia, jotka esiteltiin ensimmäisen kerran blogiviestissä Easy Groovy Logger Injection and Log Guarding Groovydocin esittelemiseen. Groovy-käsikirjoitusta ja sen viestin Groovy-luokkia on muokattu sisällyttämään enemmän Javadoc-tyylisiä kommentteja, jotta Groovydoc voidaan paremmin näyttää toiminnassa. Tarkistettu komentosarja ja siihen liittyvät luokat näkyvät seuraavissa koodiluetteloissa.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Tartu SLF4J-, Log4j- ja Apache Commons -rekisteröintiriippuvuudet @Grab-sovelluksella ja * osoittavat Groovy 1.8: n injektoidut lokikahvat. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Ei tarvitse "napata" java.util.logging: se on osa JDK: ta! / * * Määritetään 'slf4j-simple' eikä 'slf4j-api', jotta vältetään virhe * "Luokan lataaminen epäonnistui" org.slf4j.impl.StaticLoggerBinder, joka johtuu siitä, että * ei määritetä tai enemmän kuin yksi varsinaisesta kirjauksesta sidotaan kirjastot * käytettäväksi (katso //www.slf4j.org/codes.html#StaticLoggerBinder). Yksi tulisi valita * seuraavista: 'slf4j-nop', 'slf4j-simple', 'slf4j-log4j12.jar', * 'slf4j-jdk14' tai 'logback-classic'. Esimerkki SLF4J * -riippuvuuden määrittämisestä @Grab -palvelun kautta on osoitteessa * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Esimerkki Log4j-riippuvuuden määrittämisestä @Grab -palvelun kautta on osoitteessa * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Esimerkki Apache Commonsin lokiominaisuuksien määrittämisestä @Grab -palvelun kautta on osoitteessa * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Suorita testit ... * / int headerSize = 79 printHeader (" java.util.logger ", headerSize) def javaUtilLogger = new JavaUtilLoggerClass () printHeader (" Log4j " , headerSize) def log4jLogger = new Log4jLoggerClass () printHeader ("SLF4j", headerSize) def slf4jLogger = uusi Slf4jLoggerClass () printHeader ("Apache Commons", headerSize) def commonsLogger = uusi ApacheCommonsLogger . * * @param textForHeader Otsikkoon lisättävä teksti. * @param sizeOfHeader Merkkien lukumäärä kullakin otsikkorivillä. * / def printHeader (viimeinen merkkijono textForHeader, lopullinen int sizeOfHeader) {println "=". moninkertaistaa (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
tuo groovy.util.logging.Log / ** * Näyte Groovy-luokka pistämällä java.util.logging logger * luokkaan käyttämällä {@code @Log}. * / @Log-luokka JavaUtilLoggerClass {/ ** * Rakentaja. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.nimi}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Tulosta annettu arvo ja palauta se sitten osana merkkijonoa, joka osoittaa JDK: n java.util.logging-osan *. * * @param newValue Tulostettava ja palautettavaan merkkijonoon sisällytettävä arvo. * @return-merkkijono, joka osoittaa uuden arvon ja JDK java.util.loggingille. * / public merkkijono printAndReturnValue (int newValue) {println "JDK: Tulostustapa kutsutaan kohteelle $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
tuo groovy.util.logging.Log4j tuoda org.apache.log4j.Level / ** * Groovy-luokan esimerkki injektoimalla Log4j-kirjaaja * luokkaan käyttämällä {@code @ Log4j}. * / @ Log4j-luokka Log4jLoggerClass {/ ** * Rakentaja. * / Log4jLoggerClass () {// Lokitustaso on asetettava tähän, koska oletus on FATAL ja // emme käytä ulkoista Log4j-määritystiedostoa tässä esimerkissä log.setLevel (Level.INFO) println "\ nLog4j loki ($ {log.nimi}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Tulostus toimitettu arvo ja palauta se sitten osana merkkijonoa osoittava osa * Log4j: stä. * * @param newValue Tulostettava ja palautettavaan merkkijonoon sisällytettävä arvo. * @return-merkkijono, joka ilmaisee uuden arvon ja Log4j. * / public merkkijono printAndReturnValue (int newValue) {println "Log4j: Tulostustapa kutsutaan kohteelle $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
tuo groovy.util.logging.Slf4j / ** * Näyte Groovy-luokka käyttämällä {@code @ Slf4j} -toimintoa yksinkertaisen lokin julkisivun injektoimiseksi luokkaan * Java (SLF4J). * / @ Slf4j-luokka Slf4jLoggerClass {/ ** * Rakentaja. * / public Slf4jLoggerClass () {println "\ nSLF4J Kirjaaminen ($ {log.nimi}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {tämä .printAndReturnValue (2)} "} / ** * Tulosta annettu arvo ja palauta se sitten osana merkkijonoa osoittavaa osaa * SLF4J-kirjauksessa. * * @param newValue Tulostettava ja palautettavaan merkkijonoon sisällytettävä arvo. * @return-merkkijono, joka ilmaisee uuden arvon ja SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: Tulostustapa on haettu kohteelle $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
tuo groovy.util.logging.Commons / ** * Näyte Groovy-luokka käyttämällä {@code @Commons} -toimintoa injektoidaksesi Apache Commons -loggeri * luokkaan. * / @Commons class ApacheCommonsLoggerClass {/ ** * Rakentaja. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Tulosta annettu arvo ja palauta se sitten osana merkkijonoa osoittavaa osaa * Apache Commons Loggingissa. * * @param newValue Tulostettava ja palautettavaan merkkijonoon sisällytettävä arvo. * @return-merkkijono, joka ilmaisee newValue- ja Apache Commons -lokien. * / public String printAndReturnValue (int newValue) {println "Commons: Tulostustapa kutsutaan kohteelle $ {newValue}" return "Commons: $ {newValue}"}} Edellä mainittujen Groovy-komentosarjojen ja luokkien lisäksi käytän täällä myös uutta Java-luokkaa havainnollistaakseni, että Groovydoc toimii sekä Java-luokissa että Groovy-luokissa. Java-luokka ei tee paljoakaan sen lisäksi, että hän tarjoaa Javadoc-kommentit, jotka Groovydoc käsittelee.
DoNothingClass.java
/ ** * Luokka, joka ei tee mitään, mutta on täällä Java-luokka, joka kulkee * groovydocin läpi. * / public class DoNothingClass {/ ** * Yksinkertainen menetelmä, joka palauttaa kirjaimellisen "Hello _addressee_!" merkkijono, jossa * _osoite_ on tälle menetelmälle annettu nimi. * * @param adressaatti Nimi palautetulle tervehdykselle, jolle osoitetaan. * @return "Hei!" * / public String sayHello (viimeinen merkkijono vastaanottaja) {return "Hei" + vastaanottaja; } / ** * Suoritettava päätoiminto. * / public static void main (viimeiset merkkijono [] argumentit) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dustin"); } / ** * Anna merkkijonoesitys tälle objektille. * * @return Minun merkkijonoesitys. * / @Override public String toString () {return "Hei!"; }} Suorita Groovydoc komentorivillä
Kun yllä olevat Groovy-komentosarja, Groovy-luokat ja Java-luokka ovat valmiina, on aika kiinnittää huomiota Groovydocin suorittamiseen näitä luokkia ja komentosarjaa vastaan. Kuten Javadocin tapauksessa, Groovydoc voidaan suorittaa komentoriviltä. Komento, jolla Groovydoc suoritetaan yllä olevia luokkia ja komentosarjoja vastaan (olettaen, että ne kaikki ovat samassa hakemistossa, jossa komento suoritetaan) näyttää tältä:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -indowtitle "Groovy 1.8 Logging Example"-header "Groovy 1.8 Logging (Inspired by Actual Events)" -footer "Inspired by Todelliset tapahtumat: Logging in Groovy 1.8 "-doctitle" Kirjoittaminen Groovy 1.8 -versiossa osoitettu "* .groovy * .java Kaikki yllä oleva komento suoritetaan yhdellä rivillä. Luettavuuden parantamiseksi olen kuitenkin lisännyt rivinvaihtoja komennon hajottamiseksi.
groovydoc -luokkarata C: \ groovy-1.8.0 \ lib \ -d output -indowtitle "Groovy 1.8 Logging Example"-header "Groovy 1.8 Logging (Inspired by Actual Events)" -footer "Inspired by Actual Events: Logging in Groovy 1.8 "-doctitle" Sisäänkirjautuminen Groovy 1.8 -versiossa osoitettu "* .groovy * .java Groovydoc-komennon parametrit näyttävät tutuilta kaikille, jotka ovat käyttäneet javadocia komentoriviltä. Komennon viimeinen osa määrittelee, että groovydoc tulisi ajaa Groovy- ja Java-koodia vastaan.
Suorita Groovydoc Antilta
Groovydociin pääsee helposti myös mukautetun Ant-tehtävän kautta, kuten Groovy-käyttöoppaassa kuvataan. Groovydoc Ant -tehtävän käyttäminen on melko helppoa asettamalla ensin sopiva taskdef ja sitten käyttämällä määritettyä tunnistetta. Tämä näkyy seuraavassa asiaankuuluvan XML-katkelmassa build.xml tiedosto.
Ant ant build.xml -tiedoston osat, jotka osoittavat groovydoc-tehtävän
Muurahaisen osa build.xml Yllä oleva kuva vastaa suunnilleen komentorivillä käytettyä. Groovydocin saatavuus Antin kautta on tärkeää, koska se helpottaa Groovy-dokumentaation rakentamista integroituna Ant-pohjaisiin rakennusjärjestelmiin.
Groovydocin tuottama dokumentaatio
Koska jokainen lähestymistapa Groovy-dokumentaation luomiseen Groovydocin kautta (komentoriville tai Ant-pohjainen) toimii suunnilleen samalla tavalla kuin toinen, keskityn nyt HTML-tulosteeseen, joka voisi tulla jommastakummasta lähestymistavasta. Seuraavassa kuvakaappaussarjassa näkyy luotu dokumentaatio aloittaen pääsivulla, jota seuraa DefaultPackage -sivu (jätin laiskasti komentosarjan, Groovy-luokat ja Java-luokan nykyiseen hakemistoon ilman pakettideklarointia), jota seuraa tulos Groovy-komentosarjalle, esimerkiksi Groovy-luokalle ja keksitylle Java-luokalle. Kolme viimeistä kuvaa auttavat erottamaan Groovy-komentosarjan tuotoksen Groovy-luokan ja Java-luokan välillä.
Groovydoc-pääsivun esimerkki
Groovydoc-lähtö esimerkkipaketille (DefaultPackage)
Groovydoc-lähtö Groovy-komentosarjan esimerkille
Groovydoc-tuotos esimerkiksi Groovy-luokalle
Groovydoc-lähtö Java-luokan esimerkille
Edellä esitetystä Groovydoc-tuotoksesta voidaan tehdä useita havaintoja. Ensinnäkin Groovy-komentosarjan luotu dokumentaatio dokumentoi vain skriptissä määritellyt menetelmät (mukaan lukien implisiittinen tärkein menetelmä). Mikä ei ole niin ilmeistä yllä olevista staattisista kuvista, on se, että itse asiassa Groovydoc-lähtöä ei luoda lainkaan käsikirjoitukselle, ellei ainakin yksi menetelmä ole määritelty nimenomaisesti komentosarjassa. Jos yksi menetelmä on määritelty komentosarjassa, Groovydoc-lähtö generoidaan kaikille määritetyille menetelmille ja implisiittiselle päämenetelmälle. Vaihtoehto -nomainforscripts voidaan välittää Groovydocille, jotta implisiittiselle ei luoda Groovydocia tärkein menetelmä. Tämän vaihtoehdon lisäämisen tulos näkyy seuraavaksi (huomaa, että tärkeindokumentaatiota ei enää näytetä).
-nommainforscripts vaihtoehto on mukava, koska emme usein halua tärkein toiminto on dokumentoitu implisiittisesti skripteihimme. Todellakin tärkein toiminto on yleensä "piilotettu" meiltä käsikirjoittajina ja ylläpitäjinä.
Toinen havainto Groovydocin tuottaman lähdön tarkastelusta on, että luotu lähtö erottaa Groovyn ja Java-lähdekoodin. Groovy-skriptit ja luokat on merkitty "[Groovy]" ja Java-luokat on merkitty "[Java]". Tämä käy ilmi myös Groovydocin luomasta Groovy API -dokumentaatiosta, jossa näiden ominaisuuksien avulla on helppo tunnistaa, että groovy.sql.Sql ja AntBuilder ovat Java-luokkia, kun taas JmxBuilder ja SwingBuilder ovat Groovy-luokkia.
