Groovydoc blev introduceret i 2007 for at sørge for Groovy, hvad Javadoc giver for Java. Groovydoc bruges til at generere API-dokumentationen til Groovy- og Java-klasser, der sammensætter Groovy-sproget. I dette indlæg ser jeg på at påberåbe Groovydoc via kommandolinjen og via Groovy-leveret brugerdefineret Ant-opgave.
Groovy og Java kildekode med Groovydoc / Javadoc kommentarer
Jeg vil bruge tilpassede versioner af Groovy-scriptet og klasser, der først blev introduceret i mit blogindlæg Easy Groovy Logger Injection og Log Guarding for at demonstrere Groovydoc. Det vigtigste Groovy-script og Groovy-klasser fra dette indlæg er blevet ændret til at omfatte flere kommentarer i Javadoc-stil for bedre at demonstrere Groovydoc i aktion. Det reviderede script og tilknyttede klasser vises i de næste kodelister.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Grab SLF4J, Log4j og Apache Commons Logningsafhængigheder ved hjælp af @Grab og * demonstrerer Groovy 1.8s injicerede logningshåndtag. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Intet behov for at "gribe" java.util.logging: det er en del af JDK! / * * Angivelse af 'slf4j-simple' snarere end 'slf4j-api' for at undgå fejlen * "Kunne ikke indlæse klasse" org.slf4j.impl.StaticLoggerBinder ", der er forårsaget af * at angive ikke eller mere end en af den faktiske logning bindende biblioteker, der skal * bruges (se //www.slf4j.org/codes.html#StaticLoggerBinder). Man skal * vælges fra 'slf4j-nop', 'slf4j-simple', 'slf4j-log4j12.jar', * 'slf4j-jdk14' eller 'logback-classic'. Et eksempel på at specificere SLF4J * afhængighed via @Grab findes 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å at specificere Log4j-afhængighed via @Grab er på * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Et eksempel på at specificere Apache Commons Logging-afhængighed 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 ") / * * Kø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 = ny ApacheCommonsLogger ** . * * @param textForHeader Tekst, der skal medtages i overskriften. * @param sizeOfHeader Antal tegn i hver række af header. * / def printHeader (final String textForHeader, final int sizeOfHeader) {println "=". multiplicer (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
importer groovy.util.logging.Log / ** * Prøve Groovy-klasse ved hjælp af {@code @Log} til at indsprøjte 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)} "} / ** * Udskriv den angivne værdi, og returner den som en del af String, der angiver en del * af JDK's java.util.logging. * * @param newValue Værdi, der skal udskrives og inkluderes til gengæld String. * @return String, der angiver newValue og JDK til java.util.logging. * / public String printAndReturnValue (int newValue) {println "JDK: Udskrivningsmetode påkrævet for $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
import groovy.util.logging.Log4j import org.apache.log4j.Level / ** * Eksempel på Groovy-klasse ved hjælp af {@code @ Log4j} for at indsprøjte Log4j-logger * i klassen. * / @ Log4j klasse Log4jLoggerClass {/ ** * Konstruktør. * / Log4jLoggerClass () {// Det er nødvendigt at indstille logningsniveau her, fordi standard er FATAL, og // vi bruger ikke en ekstern Log4j-konfigurationsfil i dette eksempel log.setLevel (Level.INFO) println "\ nLog4j Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Udskrivning leveret værdi, og returner den derefter som en del af String, der angiver del * af Log4j. * * @param newValue Værdi, der skal udskrives og inkluderes til gengæld String. * @return String, der angiver newValue og Log4j. * / public String printAndReturnValue (int newValue) {println "Log4j: Udskrivningsmetode påkrævet for $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
importer groovy.util.logging.Slf4j / ** * Eksempel på Groovy-klasse ved hjælp af {@code @ Slf4j} til at indsprøjte Simple Logging Facade til * 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 "$ {dette .printAndReturnValue (2)} "} / ** * Udskriv den angivne værdi, og returner den derefter som en del af String, der angiver del * af SLF4J-logning. * * @param newValue Værdi, der skal udskrives og inkluderes til gengæld String. * @return String, der angiver newValue og SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: Udskrivningsmetode påkrævet for $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
import groovy.util.logging.Commons / ** * Eksempel på Groovy-klasse ved hjælp af {@code @Commons} til at indsprøjte 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)} "} / ** * Udskriv den angivne værdi, og returner den derefter som en del af String, der angiver del * af Apache Commons Logging. * * @param newValue Værdi, der skal udskrives og inkluderes til gengæld String. * @return String, der angiver logning af newValue og Apache Commons. * / public String printAndReturnValue (int newValue) {println "Commons: Udskrivningsmetode påkrævet for $ {newValue}" return "Commons: $ {newValue}"}} Ud over ovenstående Groovy-script og klasser bruger jeg også en ny Java-klasse her for at illustrere, at Groovydoc fungerer på Java-klasser såvel som Groovy-klasser. Java-klassen gør ikke meget udover at levere de Javadoc-kommentarer, der skal behandles af Groovydoc.
DoNothingClass.java
/ ** * Klasse, der ikke gør noget, men som er her for at være en Java-klasse, der køres gennem * groovydoc. * / public class DoNothingClass {/ ** * Enkel metode, der returnerer bogstaveligt "Hej _adresse_!" streng, hvor * _adresse_ er navnet på denne metode. * * @param adressat Navn på returneret hilsen, der skal adresseres til. * @return "Hej!" * / public String sayHello (final String addressee) {return "Hello", + addressee; } / ** * Hovedfunktionsfunktion. * / public static void main (final String [] argumenter) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dustin"); } / ** * Angiv strengrepræsentation af dette objekt. * * @return Stringrepræsentation af mig. * / @Override public String toString () {return "Hej!"; }} Kører Groovydoc på kommandolinjen
Med Groovy-scriptet, Groovy-klasser og Java-klasser vist ovenfor klar til brug, er det tid til at rette opmærksomheden mod at køre Groovydoc mod disse klasser og script. Som det er tilfældet med Javadoc, kan Groovydoc køres fra kommandolinjen. Kommandoen til at køre Groovydoc mod ovenstående klasser og scripts (forudsat at de alle er i samme bibliotek, hvor kommandoen køres) ser sådan ud:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "Groovy 1.8 Logging Eksempel" -header "Groovy 1.8 Logging (Inspireret af faktiske begivenheder)" -footer "Inspireret af faktiske begivenheder: Logning i Groovy 1.8 "-doctitle" Logning i Groovy 1.8 Demonstreret "* .groovy * .java Ovenstående kommando køres alle på en linje. For at forbedre læsbarheden har jeg dog tilføjet linjeskift for at nedbryde kommandoen.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "Groovy 1.8 Logging Eksempel" -header "Groovy 1.8 Logging (Inspireret af faktiske begivenheder)" -footer "Inspireret af faktiske begivenheder: Logning i Groovy 1.8 "-doctitle" Logning i Groovy 1.8 Demonstreret "* .groovy * .java Groovydoc-kommandoparametrene ser velkendte ud for alle, der har brugt javadoc fra kommandolinjen. Den sidste del af kommandoen specificerer, at groovydoc skal køres mod Groovy og Java-kode.
Kører Groovydoc fra Ant
Groovydoc kan også let åbnes via en brugerdefineret Ant-opgave som beskrevet i Groovy User Guide. Det er ret let at anvende groovydoc Ant-opgaven ved først at konfigurere den relevante taskdef og derefter ved at bruge det definerede tag. Dette demonstreres i det følgende XML-uddrag fra en relevant build.xml fil.
Dele af en Ant build.xml-fil, der demonstrerer groovydoc-opgave
Den del af myren build.xml vist ovenfor svarer omtrent til det, der bruges på kommandolinjen. At have Groovydoc tilgængelig via Ant er vigtigt, fordi det gør det lettere at integrere opbygning af Groovy-dokumentation fra Ant-baserede build-systemer.
Groovydoc genereret dokumentation
Fordi hver tilgang til generering af Groovy-dokumentation via Groovydoc (kommandolinje eller Ant-baseret) fungerer omtrent som den anden, vil jeg nu fokusere på HTML-output, der kunne komme fra begge tilgange. Den næste serie af snapshots på skærmen viser den genererede dokumentation, der starter med hovedsiden, efterfulgt af siden DefaultPackage (jeg lod dovent scriptet, Groovy-klasser og Java-klasse i den aktuelle mappe og uden nogen pakkedeklaration) efterfulgt af henholdsvis output til Groovy-scriptet, for et eksempel på Groovy-klassen og til den konstruerede Java-klasse. De sidste tre billeder hjælper med at skelne mellem output for et Groovy Script versus en Groovy-klasse versus en Java-klasse.
Groovydoc hovedsideeksempel
Groovydoc-output til eksempelpakke (standardpakke)
Groovydoc-output som eksempel på Groovy-script
Groovydoc output for eksempel Groovy klasse
Groovydoc-output til eksempel Java-klasse
Flere observationer kan foretages fra Groovydoc-output vist ovenfor. For det første dokumenterede den genererede dokumentation til Groovy-scriptet kun de metoder, der er defineret i scriptet (inklusive det implicitte vigtigste metode). Hvad der ikke er så indlysende fra de statiske billeder ovenfor er, at der faktisk ikke oprettes nogen Groovydoc-output til et script overhovedet, medmindre mindst en metode er udtrykkeligt defineret i scriptet. Hvis en metode er defineret i scriptet, genereres Groovydoc-output for alle definerede metoder og for den implicitte hovedmetode. Muligheden -nomainforscripts kan sendes til Groovydoc for ikke at generere nogen Groovydoc til det implicitte vigtigste metode. Resultatet af tilføjelse af denne mulighed vises derefter (bemærk at vigtigstedokumentation vises ikke længere).
Det -nomainforscripts mulighed er god, fordi vi ofte ikke vil have vigtigste funktion, der implicit skal dokumenteres til vores scripts. Faktisk vigtigste funktionen er typisk "skjult" for os som manuskriptforfattere og vedligeholdere.
En anden observation fra at se på Groovydoc-genereret output er, at den genererede output skelner mellem Groovy og Java-kildekode. Groovy-scripts og klasser er mærket med "[Groovy]", og Java-klasser er mærket med "[Java]." Dette er også tydeligt i den Groovydoc-genererede Groovy API-dokumentation, hvor disse funktioner gør det let at identificere, at groovy.sql.Sql og AntBuilder er Java-klasser, mens JmxBuilder og SwingBuilder er Groovy-klasser.
