Groovydoc ble introdusert i 2007 for å sørge for Groovy det Javadoc gir for Java. Groovydoc brukes til å generere API-dokumentasjon for Groovy- og Java-klassene som komponerer Groovy-språket. I dette innlegget ser jeg på å påkalle Groovydoc via kommandolinjen og via Groovy-gitt tilpasset Ant-oppgave.
Groovy og Java kildekode med Groovydoc / Javadoc kommentarer
Jeg vil bruke tilpassede versjoner av Groovy-skriptet og klassene som først ble introdusert i blogginnlegget mitt Easy Groovy Logger Injection and Log Guarding for å demonstrere Groovydoc. Det viktigste Groovy-skriptet og Groovy-klassene fra det innlegget er endret for å inkludere flere kommentarer i Javadoc-stil for bedre å demonstrere Groovydoc i aksjon. Det reviderte skriptet og tilhørende klasser vises i de neste kodelistene.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Grab SLF4J, Log4j og Apache Commons Logging avhengigheter ved hjelp av @Grab og * demonstrerer Groovy 1.8s injiserte logghåndtak. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Ingen grunn til å "gripe" java.util.logging: det er en del av JDK! / * * Spesifisere 'slf4j-enkel' i stedet for 'slf4j-api' for å unngå feilen * "Kunne ikke laste klasse" org.slf4j.impl.StaticLoggerBinder "som er forårsaket av * å angi ikke eller mer enn en av den faktiske loggingen bindende biblioteker som * skal brukes (se //www.slf4j.org/codes.html#StaticLoggerBinder). Man bør * velges fra 'slf4j-nop', 'slf4j-simple', 'slf4j-log4j12.jar', * 'slf4j-jdk14', eller 'logback-classic'. Et eksempel på å spesifisere SLF4J * avhengighet via @Grab er tilgjengelig på * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Et eksempel på å spesifisere Log4j-avhengighet via @Grab er på * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Et eksempel på å spesifisere Apache Commons loggingsavhengighet via @Grab er på * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Kjør testene ... * / int headerSize = 79 printHeader (" java.util.logger ", headerSize) def javaUtilLogger = new JavaUtilLoggerClass () printHeader (" Log4j " , headerSize) def log4jLogger = new Log4jLoggerClass () printHeader ("SLF4j", headerSize) def slf4jLogger = new Slf4jLoggerClass () printHeader ("Apache Commons", headerSize) def commonsLogger = new ApacheCommonsLogger ** . * * @param textForHeader Tekst som skal inkluderes i overskriften. * @param sizeOfHeader Antall tegn i hver rad med topptekst. * / def printHeader (final String textForHeader, final int sizeOfHeader) {println "=". multipliser (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
importer groovy.util.logging.Log / ** * Eksempel på Groovy-klasse med {@code @Log} for å injisere java.util.logging logger * i klassen. * / @Log klasse JavaUtilLoggerClass {/ ** * Konstruktør. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Skriv ut gitt verdi og returner den deretter som en del av String som indikerer del * av JDKs java.util.logging. * * @param newValue Verdi som skal skrives ut og inkluderes i retur String. * @return String som indikerer newValue og JDK for java.util.logging. * / public String printAndReturnValue (int newValue) {println "JDK: Utskriftsmetode påkalt for $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
import groovy.util.logging.Log4j import org.apache.log4j.Level / ** * Eksempel på Groovy-klasse ved hjelp av {@code @ Log4j} for å injisere Log4j logger * i klassen. * / @ Log4j klasse Log4jLoggerClass {/ ** * Konstruktør. * / Log4jLoggerClass () {// Det er nødvendig å angi loggenivå her fordi standard er FATAL og // vi bruker ikke en ekstern Log4j-konfigurasjonsfil i dette eksemplet log.setLevel (Level.INFO) println "\ nLog4j Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Utskrift gitt verdi og returner den deretter som en del av String som indikerer del * av Log4j. * * @param newValue Verdi som skal skrives ut og inkluderes i retur String. * @return String som indikerer newValue og Log4j. * / public String printAndReturnValue (int newValue) {println "Log4j: Utskriftsmetode påkalt for $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
importer groovy.util.logging.Slf4j / ** * Eksempel på Groovy-klasse ved hjelp av {@code @ Slf4j} for å injisere Simple Logging Facade for * Java (SLF4J) logger i klassen. * / @ Slf4j klasse Slf4jLoggerClass {/ ** * Konstruktør. * / public Slf4jLoggerClass () {println "\ nSLF4J Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {this .printAndReturnValue (2)} "} / ** * Skriv ut gitt verdi, og returner den deretter som en del av streng som indikerer del * av SLF4J-logging. * * @param newValue Verdi som skal skrives ut og inkluderes i retur String. * @return String som indikerer newValue og SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: Utskriftsmetode påkalt for $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
importere groovy.util.logging.Commons / ** * Eksempel på Groovy-klasse ved hjelp av {@code @Commons} for å injisere Apache Commons logger * i klassen. * / @Commons klasse ApacheCommonsLoggerClass {/ ** * Konstruktør. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Skriv ut gitt verdi og returner den som en del av String som indikerer del * av Apache Commons Logging. * * @param newValue Verdi som skal skrives ut og inkluderes i retur String. * @return String som indikerer logging av newValue og Apache Commons. * / public String printAndReturnValue (int newValue) {println "Commons: Utskriftsmetode påkalt for $ {newValue}" return "Commons: $ {newValue}"}} I tillegg til ovennevnte Groovy-skript og klasser, bruker jeg også en ny Java-klasse her for å illustrere at Groovydoc fungerer på Java-klasser så vel som Groovy-klasser. Java-klassen gjør ikke mye foruten å gi Javadoc-kommentarene som skal behandles av Groovydoc.
DoNothingClass.java
/ ** * Klasse som ikke gjør noe, men som er her for å være en Java-klasse kjørt gjennom * groovydoc. * / public class DoNothingClass {/ ** * Enkel metode som gir bokstavelig "Hello _addressee_!" streng der * _addressee_ er navnet på denne metoden. * * @paramottaker Navn for returnert hilsen som skal rettes til. * @return "Hallo!" * / public String sayHello (final String addressee) {return "Hello," + addressee; } / ** * Hoved kjørbar funksjon. * / public static void main (final String [] argumenter) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dustin"); } / ** * Gi strengrepresentasjon av dette objektet. * * @return Stringrepresentasjon av meg. * / @Override public String toString () {return "Hello!"; }} Kjører Groovydoc på kommandolinjen
Med Groovy-skriptet, Groovy-klasser og Java-klasser som vist ovenfor, er det på tide å rette oppmerksomheten mot å kjøre Groovydoc mot disse klassene og skriptet. Som tilfellet er med Javadoc, kan Groovydoc kjøres fra kommandolinjen. Kommandoen for å kjøre Groovydoc mot de ovennevnte klassene og skriptene (forutsatt at de alle er i samme katalog der kommandoen kjøres) ser omtrent slik ut:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "Groovy 1.8 Logging Eksempel" -header "Groovy 1.8 Logging (Inspirert av faktiske hendelser)" -footer "Inspirert av faktiske hendelser: Logging in Groovy 1.8 "-doctitle" Logging in Groovy 1.8 Demonstrated "* .groovy * .java Ovennevnte kommando kjøres alle på en linje. For forbedret lesbarhet har jeg imidlertid lagt til linjeskift for å bryte kommandoen.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "Groovy 1.8 Logging Eksempel" -header "Groovy 1.8 Logging (Inspirert av faktiske hendelser)" -footer "Inspirert av faktiske hendelser: Logging in Groovy 1.8 "-doctitle" Logging in Groovy 1.8 Demonstrated "* .groovy * .java Groovydoc-kommandoparametrene ser kjent ut for alle som har brukt javadoc fra kommandolinjen. Den siste delen av kommandoen spesifiserer at groovydoc skal kjøres mot Groovy og Java-kode.
Kjører Groovydoc fra Ant
Groovydoc er også lett tilgjengelig via en tilpasset Ant-oppgave som beskrevet i Groovy User Guide. Det er ganske enkelt å bruke groovydoc Ant-oppgaven ved først å sette opp riktig oppgavedef og deretter ved å bruke den definerte taggen. Dette demonstreres i følgende XML-kodebit fra en relevant build.xml fil.
Deler av en maur build.xml-fil som demonstrerer groovydoc-oppgave
Delen av mauren build.xml vist ovenfor tilsvarer omtrent det som brukes på kommandolinjen. Å ha Groovydoc tilgjengelig via Ant er viktig fordi det gjør det lettere å integrere bygging av Groovy-dokumentasjon fra Ant-baserte byggesystemer.
Groovydoc generert dokumentasjon
Fordi hver tilnærming til å generere Groovy-dokumentasjon via Groovydoc (kommandolinje eller Ant-basert) fungerer omtrent som den andre, vil jeg nå fokusere på HTML-utdata som kan komme fra begge tilnærmingene. Den neste serien med skjermbilder viser den genererte dokumentasjonen som begynner med hovedsiden, etterfulgt av DefaultPackage-siden (jeg la lat skript, Groovy-klasser og Java-klasse i gjeldende katalog og uten noen pakkedeklarasjon), fulgt av henholdsvis utdata for Groovy-skriptet, for et eksempel Groovy-klasse og for den konstruerte Java-klassen. De tre siste bildene hjelper til med å skille mellom utdataene for en Groovy Script versus en Groovy-klasse versus en Java-klasse.
Groovydoc hovedsideeksempel
Groovydoc-utgang for eksempelpakke (standardpakke)
Groovydoc-utdata for eksempel Groovy Script
Groovydoc-utgang for eksempel Groovy-klasse
Groovydoc-utgang for eksempel Java-klasse
Flere observasjoner kan gjøres fra Groovydoc-produksjonen vist ovenfor. For det første dokumenterte den genererte dokumentasjonen for Groovy-skriptet bare metodene som er definert i skriptet (inkludert den implisitte hoved- metode). Det som ikke er så tydelig fra de statiske bildene ovenfor, er at det faktisk ikke blir opprettet noen Groovydoc-utgang for et skript i det hele tatt, med mindre minst en metode er eksplisitt definert i skriptet. Hvis en metode er definert i skriptet, genereres Groovydoc-utdata for alle definerte metoder og for den implisitte hovedmetoden. Valget -nomainforscripts kan overføres til Groovydoc for ikke å få Groovydoc generert for det implisitte hoved- metode. Resultatet av å legge til dette alternativet vises neste (merk at hoved-Dokumentasjonen vises ikke lenger).
De -normale utskrifter alternativet er fint fordi vi ofte ikke vil ha hoved- funksjonen som skal implisitt dokumenteres for skriptene våre. Faktisk, den hoved- funksjonen er vanligvis "skjult" for oss som manusforfattere og vedlikeholdere.
En annen observasjon fra å se på Groovydoc-generert output er at den genererte output skiller mellom Groovy og Java kildekode. Groovy-skript og klasser er merket med "[Groovy]" og Java-klasser er merket med "[Java]." Dette er også tydelig i Groovydoc-generert Groovy API-dokumentasjon der disse funksjonene gjør det enkelt å identifisere at groovy.sql.Sql og AntBuilder er Java-klasser mens JmxBuilder og SwingBuilder er Groovy-klasser.
