Program Groovydoc bol predstavený v roku 2007 s cieľom poskytnúť Groovy to, čo Javadoc poskytuje pre Javu. Groovydoc sa používa na generovanie dokumentácie API pre triedy Groovy a Java, ktoré tvoria jazyk Groovy. V tomto príspevku sa pozriem na vyvolanie programu Groovydoc pomocou príkazového riadku a prostredníctvom vlastnej úlohy Ant od Groovy.
Zdrojový kód Groovy a Java s komentármi Groovydoc / Javadoc
Na demonštráciu programu Groovydoc použijem upravené verzie skriptu Groovy a triedy, ktoré som prvýkrát predstavil v mojom blogovom príspevku Easy Groovy Logger Injection a Log Guarding. Hlavný skript Groovy a triedy Groovy z tohto príspevku boli upravené tak, aby obsahovali viac komentárov v štýle Javadoc, aby lepšie demonštrovali Groovydoc v akcii. Revidovaný skript a súvisiace triedy sú uvedené v ďalších zoznamoch kódov.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Získať závislosti SLF4J, Log4j a Apache Commons pomocou protokolu @Grab a * demonštrovať injektované úchyty protokolovania Groovy 1.8. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Nie je potrebné „chytať“ java.util.logging: je to súčasť JDK! / * * Zadaním výrazu 'slf4j-simple' namiesto 'slf4j-api' sa zabráni chybe * "Nepodarilo sa načítať trieda" org.slf4j.impl.StaticLoggerBinder ", ktorá je spôsobená * zadaním žiadneho alebo viacerých skutočných protokolovaní použijú sa knižnice väzieb, ktoré sa majú * používať (pozri //www.slf4j.org/codes.html#StaticLoggerBinder). Jeden by mal byť * vybraný z 'slf4j-nop', 'slf4j-simple', 'slf4j-log4j12.jar', * „slf4j-jdk14“ alebo „logback-classic“. Príklad špecifikovania závislosti SLF4J * prostredníctvom @Grab je k dispozícii na * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Príklad určenia závislosti Log4j cez @Grab je na * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Príklad určenia závislosti Apache Commons Logging cez @Grab je at * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-loging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Spustiť testy ... * / int headerSize = 79 printHeader (" java.util.logger ", headerSize) def javaUtilLogger = nový JavaUtilLoggerClass () printHeader (" Log4j ") , headerSize) def log4jLogger = nový Log4jLoggerClass () printHeader ("SLF4j", headerSize) def slf4jLogger = nový Slf4jLoggerClass () printHeader ("Apache Commons", headerSize) def commonsLogger = nový ApacheCommonsLoggerClass () s textom . * * @param textForHeader Text, ktorý sa má zahrnúť do hlavičky. * @param sizeOfHeader Počet znakov v každom riadku hlavičky. * / def printHeader (konečný reťazec textForHeader, konečný int sizeOfHeader) {println "=". multiply (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
importovať groovy.util.logging.Log / ** * Ukážka triedy Groovy pomocou nástroja {@code @Log} na vloženie java.util.logging loggeru * do triedy. * / @Log trieda JavaUtilLoggerClass {/ ** * konštruktér. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Vytlačte zadanú hodnotu a potom ju vráťte ako súčasť reťazca označujúceho časť * súboru java.util.logging JDK. * * @param newValue Hodnota, ktorá sa má vytlačiť a zahrnúť do spätného reťazca. * @return Reťazec označujúci newValue a JDK pre java.util.logging. * / public String printAndReturnValue (int newValue) {println "JDK: Bola vyvolaná metóda tlače pre $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
import groovy.util.logging.Log4j import org.apache.log4j.Level / ** * Ukážka triedy Groovy pomocou {@code @ Log4j} na vloženie Log4j loggeru * do triedy. * / @ Log4j trieda Log4jLoggerClass {/ ** * konštruktér. * / Log4jLoggerClass () {// Je potrebné tu nastaviť úroveň protokolovania, pretože predvolená hodnota je FATAL a // v tomto príklade nepoužívame externý konfiguračný súbor Log4j log.setLevel (Level.INFO) println "\ nLog4j Prihlásenie ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "}} ** ** Tlač poskytnutá hodnotu a potom ju vráťte ako súčasť reťazca označujúceho časť * Log4j. * * @param newValue Hodnota, ktorá sa má vytlačiť a zahrnúť do spätného reťazca. * @return Reťazec označujúci newValue a Log4j. * / public String printAndReturnValue (int newValue) {println "Log4j: Bola vyvolaná metóda tlače pre $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
importovať groovy.util.logging.Slf4j / ** * Ukážka triedy Groovy pomocou aplikácie {@code @ Slf4j} na vloženie Simple Logging Facade pre * Java (SLF4J) logger do triedy. * / @ Slf4j trieda Slf4jLoggerClass {/ ** * konštruktér. * / public Slf4jLoggerClass () {println "\ nSLF4J Prihlásenie ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {this .printAndReturnValue (2)} "} / ** * Vytlačte poskytnutú hodnotu a potom ju vráťte ako súčasť reťazca označujúceho časť * protokolovania SLF4J. * * @param newValue Hodnota, ktorá sa má vytlačiť a zahrnúť do spätného reťazca. * @return Reťazec označujúci newValue a SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: Bola vyvolaná metóda tlače pre $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
importovať groovy.util.logging.Commons / ** * Ukážka triedy Groovy pomocou nástroja {@code @Commons} na vloženie záznamníka Apache Commons * do triedy. * / @Commons trieda ApacheCommonsLoggerClass {/ ** * konštruktér. * / public ApacheCommonsLoggerClass () {println "\ nProtokolovanie Apache Commons ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Vytlačte poskytnutú hodnotu a potom ju vráťte ako súčasť reťazca označujúceho časť * protokolovania Apache Commons. * * @param newValue Hodnota, ktorá sa má vytlačiť a zahrnúť do spätného reťazca. * @return Reťazec označujúci newValue a protokolovanie Apache Commons. * / public String printAndReturnValue (int newValue) {println "Commons: Bola vyvolaná metóda tlače pre $ {newValue}" return "Commons: $ {newValue}"}} Okrem vyššie uvedeného skriptu a tried Groovy tu používam aj novú triedu Java, aby som ilustroval, že Groovydoc funguje na triedach Java aj Groovy. Trieda Java toho veľa neurobí, okrem poskytovania Javadoc komentárov, ktoré má Groovydoc spracovať.
DoNothingClass.java
/ ** * Trieda, ktorá nerobí nič, ale má tu byť triedou Java, ktorá bude bežať cez * groovydoc. * / public class DoNothingClass {/ ** * Jednoduchá metóda, ktorá vracia doslovné „Hello _addressee_!“ reťazec, kde * _addressee_ je názov poskytnutý tejto metóde. * * @param addressee Meno vráteného pozdravu, ktorý bude adresovaný. * @return „Ahoj!“ * / public String sayHello (konečný adresát reťazca) {návrat „Dobrý deň,“ + adresát; } / ** * Hlavná spustiteľná funkcia. * / public static void main (final argumenty String []) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dustin"); } / ** * Poskytnite reťazcovú reprezentáciu tohto objektu. * * @return Reťazcové zastúpenie mňa. * / @Override public String toString () {return "Ahoj!"; }} Spustenie programu Groovydoc na príkazovom riadku
Keď sú skript Groovy, triedy Groovy a trieda Java zobrazené vyššie pripravené na použitie, je čas obrátiť pozornosť na spustenie programu Groovydoc proti týmto triedam a skriptu. Rovnako ako v prípade Javadoc, aj Groovydoc je možné spustiť z príkazového riadku. Príkaz na spustenie programu Groovydoc proti vyššie uvedeným triedam a skriptom (za predpokladu, že sú všetky v rovnakom adresári, v ktorom je príkaz spustený) vyzerá takto:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d výstup -windowtitle "Groovy 1.8 Príklad prihlásenia" -header "Groovy 1.8 Prihlásenie (inšpirované skutočnými udalosťami)" -footer "inšpirované skutočnými udalosťami: prihlásené do Groovy 1.8 "-doctitle" Prihlásenie do Groovy 1.8 Demonštrované "* .groovy * .java Vyššie uvedený príkaz je spustený na jednom riadku. Pre lepšiu čitateľnosť som však pridal zlomy riadkov, aby som rozbil príkaz.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d výstup -windowtitle "Groovy 1.8 Príklad prihlásenia" -header "Groovy 1.8 Prihlásenie (inšpirované skutočnými udalosťami)" -footer "inšpirované skutočnými udalosťami: prihlásené do Groovy 1.8 "-doctitle" Prihlásenie do Groovy 1.8 Demonštrované "* .groovy * .java Parametre príkazu groovydoc vyzerajú povedome každému, kto použil príkazový riadok javadoc. Posledná časť príkazu určuje, že groovydoc sa má spustiť proti Groovy a Java kódu.
Spustenie programu Groovydoc z Ant
Groovydoc je tiež ľahko prístupný pomocou vlastnej úlohy Ant, ako je popísané v Groovy User Guide. Aplikáciu úlohy groovydoc Ant je celkom ľahké vykonať tak, že najskôr nastavíte príslušný taskdef a potom použijete túto definovanú značku. To je demonštrované v nasledujúcom útržku XML od relevantného build.xml spis.
Časti súboru Ant build.xml, ktorý demonštruje úlohu groovydoc
Časť Ant build.xml vyššie je zhruba ekvivalentný s príkazom použitým v príkazovom riadku. Mať Groovydoc k dispozícii prostredníctvom Ant je dôležité, pretože to uľahčuje integráciu vytvárania dokumentácie Groovy zo systémov zostavovania založených na Ant.
Dokumentácia generovaná programom Groovydoc
Pretože každý prístup k generovaniu dokumentácie Groovy prostredníctvom programu Groovydoc (príkazového riadku alebo na báze Ant) funguje rovnako ako ten druhý, zameriam sa teraz na výstup HTML, ktorý môže pochádzať z oboch prístupov. Ďalšia séria snímok obrazovky zobrazuje vygenerovanú dokumentáciu začínajúcu na hlavnej stránke, za ktorou nasleduje stránka DefaultPackage (lenivo som nechal skript, triedy Groovy a triedu Java v aktuálnom adresári a bez akejkoľvek deklarácie balíka), za ktorým nasleduje výstup pre skript Groovy, napríklad pre triedu Groovy a pre vykonštruovanú triedu Java. Posledné tri obrázky pomáhajú rozlíšiť medzi výstupom pre Groovy Script verzus triedu Groovy verzus triedu Java.
Príklad hlavnej stránky Groovydoc
Výstup Groovydoc pre ukážkový balík (DefaultPackage)
Výstup Groovydoc pre príklad Groovy Script
Výstup Groovydoc pre príklad triedy Groovy
Groovydoc výstup pre príklad triedy Java
Z vyššie uvedeného výstupu Groovydoc je možné urobiť niekoľko pozorovaní. Najskôr vygenerovaná dokumentácia pre skript Groovy dokumentovala iba metódy definované v skripte (vrátane implicitných hlavný metóda). Čo nie je tak zrejmé zo statických obrázkov vyššie, je, že v skutočnosti sa pre skript vôbec nevytvorí žiadny výstup Groovydoc, pokiaľ v skripte nie je explicitne definovaná aspoň jedna metóda. Ak je v skripte definovaná jedna metóda, potom sa výstup Groovydoc vygeneruje pre všetky definované metódy a pre implicitnú hlavnú metódu. Možnosť -názovskripty možno odovzdať do programu Groovydoc, aby sa implicitne nevygeneroval žiadny program Groovydoc hlavný metóda. Ďalej sa zobrazuje výstup pridania tejto možnosti (všimnite si, že hlavnýdokumentácia sa už nezobrazuje).
The -nomainskripty možnosť je pekná, pretože často nechceme hlavný funkcia, ktorá má byť pre naše skripty implicitne zdokumentovaná. Skutočne hlavný Táto funkcia je pre nás ako scenáristov a správcov obvykle „skrytá“.
Druhým pozorovaním pri pohľade na výstup generovaný Groovydoc je, že vygenerovaný výstup rozlišuje medzi zdrojovým kódom Groovyd a Java. Groovy skripty a triedy sú označené značkou „[Groovy]“ a triedy Java sú označené značkou „[Java].“ To je tiež zrejmé v dokumentácii k Groovydoc generovanému API API, kde táto vlastnosť uľahčuje identifikáciu, že groovy.sql.Sql a AntBuilder sú triedy Java, zatiaľ čo JmxBuilder a SwingBuilder sú triedy Groovy.
