Groovydoc byl představen v roce 2007, aby poskytl Groovy to, co Javadoc poskytuje pro Javu. Groovydoc se používá ke generování dokumentace API pro třídy Groovy a Java, které tvoří jazyk Groovy. V tomto příspěvku se podívám na vyvolání Groovydoc prostřednictvím příkazového řádku a přes vlastní úkol Ant poskytnutý Groovydoc.
Zdrojový kód Groovy a Java s komentáři Groovydoc / Javadoc
Pro demonstraci Groovydoc použiji upravené verze skriptu a tříd Groovy, které jsem poprvé představil ve svém blogovém příspěvku Easy Groovy Logger Injection a Log Guarding. Hlavní skript Groovy a třídy Groovy z tohoto příspěvku byly upraveny tak, aby obsahovaly více komentářů ve stylu Javadoc, aby lépe demonstrovaly Groovydoc v akci. Revidovaný skript a přidružené třídy jsou zobrazeny v následujících výpisy kódu.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Popadněte závislosti protokolování SLF4J, Log4j a Apache Commons pomocí @Grab a * předveďte injekční úchyty protokolování Groovy 1.8. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Není třeba „chytat“ java.util.logging: je to součást JDK! / * * Určení 'slf4j-simple' místo 'slf4j-api', aby se zabránilo chybě * "Nepodařilo se načíst třídu" org.slf4j.impl.StaticLoggerBinder ", která je způsobena * specifikováním žádného nebo více než jednoho skutečného protokolování budou použity vazebné knihovny * (viz //www.slf4j.org/codes.html#StaticLoggerBinder). Jeden by měl být * vybrán z 'slf4j-nop', 'slf4j-simple', 'slf4j-log4j12.jar', * 'slf4j-jdk14' nebo 'logback-classic'. Příklad určení závislosti SLF4J * pomocí @Grab je k dispozici na * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Příklad určení závislosti Log4j pomocí @Grab je na * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Příklad určení závislosti protokolování Apache Commons pomocí @Grab je at * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Spusťte 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 () . * * @param textForHeader Text, který má být zahrnut do záhlaví. * @param sizeOfHeader Počet znaků v každém řádku záhlaví. * / def printHeader (final String textForHeader, final int sizeOfHeader) {println "=". multiply (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
importovat groovy.util.logging.Log / ** * Ukázková třída Groovy pomocí {@code @Log} pro vložení java.util.logging loggeru * do třídy. * / @Log třída JavaUtilLoggerClass {/ ** * Konstruktor. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Vytiskněte poskytnutou hodnotu a poté ji vraťte jako součást řetězce označujícího část * jDK java.util.logging. * * @param newValue Hodnota k vytištění a zahrnutí do návratového řetězce. * @return Řetězec označující newValue a JDK pro java.util.logging. * / public String printAndReturnValue (int newValue) {println "JDK: Byla vyvolána metoda tisku pro $ {newValue}" návrat "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
import groovy.util.logging.Log4j import org.apache.log4j.Level / ** * Ukázková třída Groovy pomocí {@code @ Log4j} pro vložení Log4j loggeru * do třídy. * / @ Log4j třída Log4jLoggerClass {/ ** * konstruktor. * / Log4jLoggerClass () {// Je nutné zde nastavit úroveň protokolování, protože výchozí hodnota je FATAL a // v tomto příkladu nepoužíváme externí konfigurační soubor Log4j log.setLevel (Level.INFO) println "\ nLog4j Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "}} ** ** Tisk k dispozici hodnotu a poté ji vrátit jako součást řetězce označujícího část * Log4j. * * @param newValue Hodnota k vytištění a zahrnutí do návratového řetězce. * @return Řetězec označující newValue a Log4j. * / public String printAndReturnValue (int newValue) {println "Log4j: Byla vyvolána metoda tisku pro $ {newValue}" návrat "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
importujte groovy.util.logging.Slf4j / ** * Ukázková třída Groovy pomocí aplikace {@code @ Slf4j} pro vložení Simple Logging Facade pro * Java (SLF4J) logger do třídy. * / @ Slf4j třída Slf4jLoggerClass {/ ** * konstruktor. * / public Slf4jLoggerClass () {println "\ nSLF4J Protokolování ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {this .printAndReturnValue (2)} "} / ** * Vytiskněte poskytnutou hodnotu a poté ji vraťte jako součást řetězce označujícího část * protokolování SLF4J. * * @param newValue Hodnota k vytištění a zahrnutí do návratového řetězce. * @return Řetězec označující newValue a SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: Metoda tisku vyvolána pro $ {newValue}" návrat "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
importujte groovy.util.logging.Commons / ** * Ukázková třída Groovy pomocí {@code @Commons} k vložení Apache Commons loggeru * do třídy. * / @Commons třída ApacheCommonsLoggerClass {/ ** * konstruktor. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Vytiskněte zadanou hodnotu a poté ji vraťte jako součást řetězce označujícího část * protokolování Apache Commons. * * @param newValue Hodnota k vytištění a zahrnutí do návratového řetězce. * @return Řetězec označující newValue a protokolování Apache Commons. * / public String printAndReturnValue (int newValue) {println "Commons: Byla vyvolána metoda tisku pro $ {newValue}" return "Commons: $ {newValue}"}} Kromě výše uvedeného skriptu a tříd Groovy používám zde také novou třídu Java, abych ilustroval, že Groovydoc funguje na třídách Java i na třídách Groovy. Třída Java nedělá mnoho kromě toho, že poskytuje komentáře Javadoc, které má Groovydoc zpracovat.
DoNothingClass.java
/ ** * Třída, která nic nedělá, ale je zde jako třída Java, která běží přes * groovydoc. * / public class DoNothingClass {/ ** * Jednoduchá metoda, která vrací doslovné „Hello _addressee_!“ řetězec, kde * _addressee_ je název poskytnutý této metodě. * * @param addressee Jméno vráceného pozdravu, který má být adresován. * @return „Ahoj!“ * / public String sayHello (konečný adresář řetězce) {návrat "Hello," + adresát; } / ** * Hlavní spustitelná funkce. * / public static void main (final String [] argumenty) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dustin"); } / ** * Poskytněte řetězcovou reprezentaci tohoto objektu. * * @return Řetězcové vyjádření mě. * / @Override public String toString () {return "Hello!"; }} Spuštění programu Groovydoc na příkazovém řádku
S výše uvedeným skriptem Groovy, třídami Groovy a třídou Java je připraveno jít, je čas obrátit pozornost na spuštění programu Groovydoc proti těmto třídám a skriptu. Stejně jako v případě Javadoc lze Groovydoc spustit z příkazového řádku. Příkaz pro spuštění Groovydoc proti výše uvedeným třídám a skriptům (za předpokladu, že jsou všechny ve stejném adresáři, ve kterém je příkaz spuštěn) vypadá takto:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d výstup -windowtitle "Groovy 1.8 Příklad protokolování" -header "Groovy 1.8 Logování (inspirováno skutečnými událostmi)" -footer "inspirováno skutečnými událostmi: protokolování v Groovy 1.8 "-doctitle" Přihlašování do Groovy 1.8 Ukázáno "* .groovy * .java Výše uvedený příkaz je spuštěn na jednom řádku. Pro lepší čitelnost jsem však přidal konce řádků, abych rozbil příkaz.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d výstup -windowtitle "Groovy 1.8 Příklad protokolování" -header "Groovy 1.8 Logování (inspirováno skutečnými událostmi)" -footer "inspirováno skutečnými událostmi: protokolování v Groovy 1.8 "-doctitle" Přihlašování do Groovy 1.8 Ukázáno "* .groovy * .java Parametry příkazu groovydoc vypadají dobře každému, kdo použil příkazový řádek z příkazového řádku. Poslední část příkazu určuje, že groovydoc by měl být spuštěn proti kódu Groovyd a Java.
Spuštění programu Groovydoc z Ant
Do aplikace Groovydoc lze také snadno získat přístup pomocí vlastní úlohy Ant, jak je popsáno v uživatelské příručce k aplikaci Groovydoc. Je poměrně snadné použít úkol groovydoc Ant tak, že nejprve nastavíte příslušný taskdef a poté použijete tuto definovanou značku. To je ukázáno v následujícím fragmentu XML od příslušného build.xml soubor.
Části souboru Ant build.xml Demonstrace úlohy groovydoc
Část mravence build.xml výše je zhruba ekvivalentní s příkazovým řádkem. Mít Groovydoc k dispozici prostřednictvím Ant je důležité, protože to usnadňuje integraci vytváření dokumentace Groovy ze sestavovacích systémů založených na Ant.
Dokumentace generovaná programem Groovydoc
Protože každý přístup ke generování dokumentace Groovy přes Groovydoc (příkazový řádek nebo Ant) funguje stejně jako ten druhý, zaměřím se nyní na výstup HTML, který by mohl pocházet z obou přístupů. Další série snímků obrazovky ukazuje vygenerovanou dokumentaci počínaje hlavní stránkou, následovanou stránkou DefaultPackage (skript, třídy Groovy a třídu Java jsem líně nechal v aktuálním adresáři a bez deklarace balíčku), následovaný výstupem pro skript Groovy, například pro třídu Groovy a pro vykonstruovanou třídu Java. Poslední tři obrázky pomáhají rozlišovat mezi výstupem pro Groovy Script oproti třídě Groovy oproti třídě Java.
Příklad hlavní stránky Groovydoc
Výstup Groovydoc pro ukázkový balíček (DefaultPackage)
Výstup Groovydoc pro příklad Groovy Script
Výstup Groovydoc pro příklad třídy Groovy
Výstup Groovydoc pro příklad třídy Java
Z výše uvedeného výstupu Groovydoc lze provést několik pozorování. Nejprve vygenerovaná dokumentace pro skript Groovy dokumentovala pouze metody definované ve skriptu (včetně implicitní hlavní metoda). Ze statických obrázků výše není tak zřejmé, že ve skutečnosti není pro skript vytvořen vůbec žádný výstup Groovydoc, pokud není ve skriptu explicitně definována alespoň jedna metoda. Pokud je ve skriptu definována jedna metoda, je výstup Groovydoc generován pro všechny definované metody a pro implicitní hlavní metodu. Možnost -nomainforscripts lze předat do Groovydoc, aby pro implicitně nebyl vygenerován žádný Groovydoc hlavní metoda. Následně se zobrazí výstup přidání této možnosti (všimněte si, že hlavnídokumentace již není zobrazena).
The -nomainskripty možnost je hezká, protože často nechceme hlavní funkce, která má být implicitně dokumentována pro naše skripty. Opravdu hlavní funkce je pro nás jako spisovatele a správce skriptů obvykle „skrytá“.
Druhým pozorováním při pohledu na výstup generovaný Groovydoc je, že generovaný výstup rozlišuje mezi zdrojovým kódem Groovyd a Java. Groovy skripty a třídy jsou označeny „[Groovy]“ a třídy Java jsou označeny „[Java].“ To je také patrné v dokumentaci Groovy API generované Groovydoc, kde tato funkce usnadňuje identifikaci, že groovy.sql.Sql a AntBuilder jsou třídy Java, zatímco JmxBuilder a SwingBuilder jsou třídy Groovy.
