Groovydoc je bil uveden leta 2007, da bi Groovyju zagotovil tisto, kar Javadoc ponuja za Javo. Groovydoc se uporablja za ustvarjanje API dokumentacije za razrede Groovy in Java, ki sestavljajo jezik Groovy. V tej objavi si ogledujem priklic Groovydoca prek ukazne vrstice in prek naloge Ant po meri, ki jo nudi Groovy.
Izvorna koda Groovy in Java s komentarji Groovydoc / Javadoc
Za predstavitev Groovydoca bom uporabil prilagojene različice skripta in razrede Groovy, ki sem jih prvič predstavil v svojem blogu, Easy Groovy Logger Injection and Log Guarding. Glavni skript Groovy in razredi Groovy iz te objave so bili spremenjeni tako, da vključujejo več komentarjev v slogu Javadoc, da bolje prikažejo Groovydoc v akciji. Popravljeni skript in pripadajoči razredi so prikazani v naslednjih šifrantih.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Zgrabi SLF4J, Log4j in Apache Commons Zapisovanje odvisnosti z uporabo @Grab in * prikazuje Groovy 1.8 vbrizgane ročke za beleženje. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Ni treba "zagrabiti" java.util.logging: to je del JDK! / * * Navedite 'slf4j-simple' namesto 'slf4j-api', da se izognete napaki * "Razred ni uspel naložiti" org.slf4j.impl.StaticLoggerBinder ", ki jo povzroči *, če ne navede nobenega ali več dejanskih zapisov zavezujoče knjižnice za * (glej //www.slf4j.org/codes.html#StaticLoggerBinder). Eno naj bo * izbrano med 'slf4j-nop', 'slf4j-simple', 'slf4j-log4j12.jar', * 'slf4j-jdk14' ali 'logback-classic'. Primer določitve odvisnosti SLF4J * prek @Grab je na voljo na * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Primer določitve odvisnosti Log4j prek @Grab je na * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Primer določitve odvisnosti dnevnika Apache Commons prek @Grab je na * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Zaženite teste ... * / 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 commonsLoggerLo * . * * @param textForHeader Besedilo, ki bo vključeno v glavo. * @param sizeOfHeader Število znakov v vsaki vrstici glave. * / def printHeader (končni niz besedilaForHeader, končni int sizeOfHeader) {println "=". multiply (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
uvozite groovy.util.logging.Log / ** * Vzorčite razred Groovy s pomočjo {@code @Log}, da v razred vstavite java.util.logging logger *. * / @Log class JavaUtilLoggerClass {/ ** * Constructor. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Natisnite določeno vrednost in jo nato vrnite kot del niza, ki označuje del * java.util.logging JDK. * * @param newValue Vrednost, ki jo je treba natisniti in vključiti v vrnjeni niz. * @return String, ki označuje newValue in JDK za java.util.logging. * / public String printAndReturnValue (int newValue) {println "JDK: metoda tiskanja, priklicana za $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
import groovy.util.logging.Log4j import org.apache.log4j.Level / ** * Vzorčite razred Groovy z uporabo {@code @ Log4j} za vbrizgavanje zapisovalnika Log4j * v razred. * / @ Log4j razred Log4jLoggerClass {/ ** * Konstruktor. * / Log4jLoggerClass () {// Tu je treba nastaviti raven beleženja, ker je privzeto FATAL in // v tem primeru ne uporabljamo zunanje konfiguracijske datoteke Log4j log.setLevel (Level.INFO) println "\ nLog4j Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Tiskanje zagotovljeno vrednost in jo nato vrnite kot del niza, ki označuje del * Log4j. * * @param newValue Vrednost, ki jo je treba natisniti in vključiti v vrnjeni niz. * @return String, ki označuje newValue in Log4j. * / public String printAndReturnValue (int newValue) {println "Log4j: metoda tiskanja, priklicana za $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
uvozite groovy.util.logging.Slf4j / ** * Vzorčite razred Groovy z uporabo {@code @ Slf4j}, da v razred vbrizgate preprosto dnevniško fasado za zapisovalnik * Java (SLF4J). * / @ Slf4j razred Slf4jLoggerClass {/ ** * Konstruktor. * / public Slf4jLoggerClass () {println "\ nSLF4J Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {this .printAndReturnValue (2)} "} / ** * Natisnite navedeno vrednost in jo nato vrnite kot del niza, ki označuje del * beleženja SLF4J. * * @param newValue Vrednost, ki jo je treba natisniti in vključiti v vrnjeni niz. * @return String, ki označuje newValue in SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: metoda tiskanja, priklicana za $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
import groovy.util.logging.Commons / ** * Vzorčite razred Groovy z uporabo {@code @Commons}, da v razred vbrizgate zapisovalnik Apache Commons *. * / @Commons class ApacheCommonsLoggerClass {/ ** * Constructor. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Natisnite navedeno vrednost in jo nato vrnite kot del niza, ki označuje del * Apache Commons Logging. * * @param newValue Vrednost, ki jo je treba natisniti in vključiti v vrnjeni niz. * @return String, ki označuje beleženje newValue in Apache Commons. * / public String printAndReturnValue (int newValue) {println "Commons: Metoda tiskanja, ki se prikliče za $ {newValue}" return "Commons: $ {newValue}"}} Poleg zgoraj omenjenega skripta in razredov Groovy tu uporabljam tudi nov razred Java, ki ponazarja, da Groovydoc deluje tako na predavanjih Java kot tudi na razredih Groovy. Razred Java poleg navajanja komentarjev Javadoc, ki jih mora obdelati Groovydoc, ne naredi veliko.
DoNothingClass.java
/ ** * Razred, ki ne naredi ničesar, je pa tukaj razred Java, ki se izvaja skozi * groovydoc. * / javni razred DoNothingClass {/ ** * Preprosta metoda, ki vrne dobesedno "Hello _addressee_!" niz, kjer je * _addressee_ ime, navedeno tej metodi. * * @param naslovnik Ime za vrnjeni pozdrav, na katerega je treba nasloviti. * @return "Pozdravljeni!" * / public String sayHello (končni naslovnik niza) {return "Hello," + addressee; } / ** * Glavna izvršljiva funkcija. * / public static void main (final String [] argumentov) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dustin"); } / ** * Navedite nizni prikaz tega predmeta. * * @return String predstavitev mene. * / @Override public String toString () {return "Pozdravljeni!"; }} Zaženite Groovydoc v ukazni vrstici
Z zgoraj prikazanimi skripti Groovy, razredi Groovy in Java so pripravljeni za uporabo, čas je, da usmerimo pozornost na izvajanje Groovydoc proti tem razredom in skriptu. Tako kot v primeru Javadoc, lahko tudi Groovydoc zaženete iz ukazne vrstice. Ukaz za zagon Groovydoc proti zgornjim razredom in skriptom (ob predpostavki, da so vsi v istem imeniku, v katerem se izvaja ukaz) je videti nekako takole:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "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" Prijava v Groovy 1.8 Demonstrated "* .groovy * .java Zgornji ukaz se izvaja v eni vrstici. Za boljšo berljivost pa sem dodal prelome vrstic, da sem razbil ukaz.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "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" Prijava v Groovy 1.8 Demonstrated "* .groovy * .java Parametri ukaza groovydoc se zdijo znani vsem, ki so uporabljali javadoc iz ukazne vrstice. Zadnji del ukaza določa, da je treba groovydoc zagnati s kodo Groovy in Java.
Tek Groovydoc iz Ant
Do Groovydoca je enostavno dostopati tudi prek naloge Ant po meri, kot je opisano v uporabniškem priročniku Groovy. Dokaj enostavno je uporabiti nalogo groovydoc Ant, tako da najprej nastavite ustrezen taskdef in nato z uporabo te definirane oznake. To je prikazano v naslednjem delčku XML iz ustreznega build.xml mapa.
Del datoteke Ant build.xml, ki prikazuje nalogo groovydoc
Del mravlje build.xml prikazano zgoraj je približno enakovredno tistemu, ki se uporablja v ukazni vrstici. Da je Groovydoc na voljo prek Ant, je pomembno, ker olajša integracijo gradnje Groovyjeve dokumentacije iz sistemov za gradnjo na osnovi Ant.
Groovydoc generirana dokumentacija
Ker vsak pristop k ustvarjanju Groovyjeve dokumentacije prek Groovydoc (ukazne vrstice ali na osnovi Ant) deluje približno enako kot drugi, se bom zdaj osredotočil na izhod HTML, ki bi lahko prišel iz obeh pristopov. Naslednja serija posnetkov zaslona prikazuje ustvarjeno dokumentacijo, ki se začne z glavno stranjo, sledi stran DefaultPackage (skript, razrede Groovy in razred Java sem leno pustil v trenutnem imeniku in brez izjave o paketu), čemur sledi izhod za skript Groovy, na primer razred Groovy in za izmišljeni razred Java. Zadnje tri slike pomagajo razlikovati med izhodnimi podatki za Groovy Script in Groovy in Java.
Primer glavne strani Groovydoc
Izhod Groovydoc za primer paketa (privzeti paket)
Izhod Groovydoc za primer Groovy Script
Izhod Groovydoc za primer razreda Groovy
Izhod Groovydoc za primer razreda Java
Iz zgoraj prikazanega izhoda Groovydoc je mogoče dobiti več opažanj. Prvič, ustvarjena dokumentacija za skript Groovy je dokumentirala samo metode, opredeljene v skriptu (vključno z implicitnim glavni metoda). Iz zgornjih statičnih slik ni tako očitno, da v resnici za skript sploh ni ustvarjen izhod Groovydoc, razen če v skriptu ni izrecno opredeljena vsaj ena metoda. Če je v skriptu definirana ena metoda, se izhod Groovydoc ustvari za vse definirane metode in za implicitno glavno metodo. Možnost -nomaininkripti lahko prenesete na Groovydoc, da za implicitno ne ustvari nobenega Groovydoca glavni metoda. Rezultat dodajanja te možnosti je prikazan naslednji (upoštevajte, da glavniDokumentacija uporabnika ni več prikazana).
The -nommainforscripts možnost je lepa, ker si je pogosto ne želimo glavni funkcija, ki jo je treba implicitno dokumentirati za naše skripte. Dejansko je glavni funkcija je običajno "skrita" od nas kot piscev in vzdrževalcev skriptov.
Druga ugotovitev iz pogleda na Groovydoc-generiran izhod je, da ustvarjeni output razlikuje med Groovy in izvorno kodo Java. Skripti in razredi Groovy so označeni z "[Groovy]", razredi Java pa so označeni z "[Java]." To je razvidno tudi iz dokumentacije Groovy API, ki jo je ustvaril Groovydoc, kjer te funkcije olajšajo prepoznavanje, da sta groovy.sql.Sql in AntBuilder Java razreda, JmxBuilder in SwingBuilder pa Groovy.
