„Groovydoc“ buvo pristatytas 2007 m., Siekiant pateikti „Groovy“ tai, ką „Javadoc“ teikia „Java“. „Groovydoc“ naudojamas norint sukurti „Groovy“ ir „Java“ klasių, sudarančių „Groovy“ kalbą, API dokumentaciją. Šiame įraše aš žvelgiu į „Groovydoc“ iškvietimą per komandinę eilutę ir per „Groovy“ pateiktą pasirinktinę „Ant“ užduotį.
Groovy ir Java šaltinio kodas su Groovydoc / Javadoc komentarais
Norėdamas parodyti „Groovydoc“, naudosiu pritaikytas „Groovy“ scenarijaus versijas ir klases, kurios pirmą kartą buvo pristatytos mano tinklaraščio įraše „Easy Groovy Logger Injection and Log Guarding“. Pagrindinis „Groovy“ scenarijus ir „Groovy“ klasės iš šio įrašo buvo modifikuoti, įtraukiant daugiau „Javadoc“ stiliaus komentarų, kad geriau pademonstruotų „Groovydoc“. Pataisytas scenarijus ir susijusios klasės rodomos kituose kodų sąrašuose.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Paimkite SLF4J, Log4j ir Apache Commons registravimo priklausomybes naudodami @Grab ir * pademonstruokite „Groovy 1.8“ įvestas registravimo rankenas. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Nereikia „griebti“ java.util.logging: tai JDK dalis! / * * Nurodykite „slf4j-simple“, o ne „slf4j-api“, kad išvengtumėte klaidos * „Nepavyko įkelti klasės“ org.slf4j.impl.StaticLoggerBinder “, kurią sukelia * nenurodant ar daugiau nei vieno faktinio registravimo susieti bibliotekas su *, kad būtų galima naudoti (žr. //www.slf4j.org/codes.html#StaticLoggerBinder). Reikėtų pasirinkti * iš „slf4j-nop“, „slf4j-simple“, „slf4j-log4j12.jar“, * „slf4j-jdk14“ arba „logback-classic“. SLF4J * priklausomybės nurodymo per „@Grab“ pavyzdį galima rasti adresu // //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * „Log4j“ priklausomybės nurodymo per „@Grab“ pavyzdys yra * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Apache Commons Logging priklausomybės per @Grab nurodymo pavyzdys yra adresu * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin" g-api ", version =" 1.1 ") / * * Paleiskite testus ... * / 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 = naujas ApacheCommonsLogger . * * @param textForHeader Tekstas, kurį reikia įtraukti į antraštę. * @param sizeOfHeader Simbolių skaičius kiekvienoje antraštės eilutėje. * / def printHeader (final String textForHeader, final int sizeOfHeader) {println "=". padauginti (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} „JavaUtilLoggerClass.groovy“
importuokite groovy.util.logging.Log / ** * „Groovy“ klasės pavyzdį naudodami {@code @Log} ir įvesdami java.util.logging logger * į klasę. * / @Log klasė JavaUtilLoggerClass {/ ** * Konstruktorius. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Atspausdinkite pateiktą vertę ir grąžinkite ją kaip eilutės dalį, nurodančią JDK java.util.logging dalį *. * * @param newValue Vertė, kurią reikia atspausdinti ir įtraukti į grąžinimo eilutę. * @return eilutė, nurodanti newValue ir JDK java.util.logging. * / public string printAndReturnValue (int newValue) {println "JDK: Naudojamas spausdinimo metodas, skirtas $ {newValue}" grąžinti "JDK: $ {newValue}"}} „Log4jLoggerClass.groovy“
importuoti groovy.util.logging.Log4j importuoti org.apache.log4j.Level / ** * Groovy klasės pavyzdys naudojant {@code @ Log4j}, norint įpiršti „Log4j logger“ į klasę. * / @ Log4j klasė Log4jLoggerClass {/ ** * Konstruktorius. * / Log4jLoggerClass () {// Čia reikia nustatyti registravimo lygį, nes numatytasis nustatymas yra FATAL ir // šiame log.setLevel (Level.INFO) println pavyzdyje nenaudojame išorinio „Log4j“ konfigūracijos failo. Lognset Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Spausdinimas pateiktas reikšmę ir tada grąžinkite ją kaip eilutės dalį, nurodančią „Log4j“ dalį *. * * @param newValue Reikšmė, kurią reikia atspausdinti ir įtraukti į grąžinimo eilutę. * @return eilutė, nurodanti newValue ir Log4j. * / public string printAndReturnValue (int newValue) {println "Log4j: naudojamas spausdinimo metodas, skirtas $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
importuokite groovy.util.logging.Slf4j / ** * „Groovy“ klasės pavyzdį naudodami {@code @ Slf4j}, kad į klasę įvestumėte paprastą žurnalo fasadą * Java (SLF4J) žurnalui. * / @ Slf4j klasė Slf4jLoggerClass {/ ** * Konstruktorius. * / public Slf4jLoggerClass () {println "\ nSLF4J registravimas ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {this .printAndReturnValue (2)} "} / ** * Atspausdinkite pateiktą vertę ir tada grąžinkite ją kaip eilutę, nurodančią SLF4J registravimo dalį *. * * @param newValue Vertė, kurią reikia atspausdinti ir įtraukti į grąžinimo eilutę. * @return eilutė, nurodanti newValue ir SLF4J. * / public string printAndReturnValue (int newValue) {println "SLF4J: Naudojamas spausdinimo metodas, skirtas $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
importuokite groovy.util.logging.Commons / ** * „Groovy“ klasės pavyzdį naudokite {@code @Commons}, kad į klasę įvestumėte „Apache Commons“ žurnalą *. * / @Commons klasė ApacheCommonsLoggerClass {/ ** * Konstruktorius. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons registravimas ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Atspausdinkite pateiktą vertę ir grąžinkite ją kaip eilutę, nurodančią„ Apache Commons Logging “dalį *. * * @param newValue Vertė, kurią reikia atspausdinti ir įtraukti į grąžinimo eilutę. * @return eilutė, nurodanti „newValue“ ir „Apache Commons“ registravimą. * / public string printAndReturnValue (int newValue) {println "Commons: Naudojamas spausdinimo metodas, skirtas $ {newValue}" return "Commons: $ {newValue}"}} Be pirmiau minėto „Groovy“ scenarijaus ir klasių, čia taip pat naudoju naują „Java“ klasę, kad iliustruočiau, kad „Groovydoc“ veikia tiek „Java“, tiek „Groovy“ klasėse. „Java“ klasė nedaug ką daro, be to, kad teikia „Javadoc“ komentarus, kuriuos turi apdoroti „Groovydoc“.
DoNothingClass.java
/ ** * Klasė, kuri nieko nedaro, bet čia yra „Java“ klasė, vykdoma per * groovydoc. * / public class DoNothingClass {/ ** * Paprastas metodas, kuris grąžina pažodinį žodį „Sveikas _adresas__!“ eilutė, kurioje * _adresas_ yra šio metodo pavadinimas. * * @param adresatas Vardas, į kurį reikia atsiųsti sveikinimą. * @return "Sveiki!" * / public String say labas (galutinis eilutės adresatas) {grąžinti "Labas" + adresatas; } / ** * Pagrindinė vykdomoji funkcija. * / public static void main (final String [] argumentai) {final DoNothingClass me = new DoNothingClass (); me.sayHello („Dustin“); } / ** * Pateikite šio objekto eilutę. * * @return Styginis man atstovavimas. * / @Paisyti viešą eilutę toString () {grąžinti „Sveiki!“; }} „Groovydoc“ paleidimas komandinėje eilutėje
Kai „Groovy“ scenarijus, „Groovy“ klasės ir „Java“ klasė, parodyta aukščiau, yra paruošta naudoti, laikas atkreipti dėmesį į „Groovydoc“ paleidimą prieš šias klases ir scenarijus. Kaip ir „Javadoc“ atveju, „Groovydoc“ galima paleisti iš komandinės eilutės. Komanda, leidžianti „Groovydoc“ paleisti prieš minėtas klases ir scenarijus (darant prielaidą, kad jie visi yra tame pačiame kataloge, kuriame vykdoma komanda) atrodo maždaug taip:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -indowtitle "Groovy 1.8 Logging Example"-header "Groovy 1.8 Logging (Inspired by Actual Events)" -footer "Inspired by Actual Events: Prisijungimas prie Groovy 1.8 "-doctitle" Prisijungimas Groovy 1.8 parodytas "* .groovy * .java Pirmiau nurodyta komanda vykdoma vienoje eilutėje. Tačiau, norėdamas pagerinti įskaitomumą, pridėjau eilutės pertraukėlių, kad suskaidytų komandą.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -indowtitle "Groovy 1.8 Logging Example"-header "Groovy 1.8 Logging (Inspired by Actual Events)" -footer "Inspired by Actual Events: Prisijungimas prie Groovy 1.8 "-doctitle" Prisijungimas Groovy 1.8 parodytas "* .groovy * .java Groovydoc komandos parametrai atrodo žinomi visiems, kurie naudojo javadoc iš komandinės eilutės. Paskutinėje komandos dalyje nurodoma, kad groovydoc turėtų būti vykdomas prieš Groovy ir Java kodus.
Bėgimas Groovydoc nuo Ant
„Groovydoc“ taip pat galima lengvai pasiekti naudodamiesi „Ant“ užduotimi, kaip aprašyta „Groovy“ vartotojo vadove. Gana lengva pritaikyti „groovydoc Ant“ užduotį pirmiausia nustatant atitinkamą taskdef ir tada naudojant tą apibrėžtą žymą. Tai įrodyta šiame XML fragmente iš atitinkamo build.xml failą.
Skruzdėlės build.xml failo dalys, rodančios groovydoc užduotį
Skruzdėlės dalis build.xml aukščiau parodyta yra maždaug tolygi komandinei eilutei naudojamai. Svarbu, kad „Groovydoc“ būtų prieinama per „Ant“, nes taip lengviau integruoti „Groovy“ dokumentacijos kūrimą iš „Ant“ pagrįstų kūrimo sistemų.
„Groovydoc“ sukurta dokumentacija
Kadangi kiekvienas požiūris į „Groovy“ dokumentacijos generavimą per „Groovydoc“ (komandinę eilutę arba „Ant“ pagrįstą) veikia maždaug taip pat, kaip ir kitas, aš dabar sutelksiu dėmesį į HTML išvestį, kuri gali atsirasti iš bet kurio požiūrio. Kitoje ekrano momentinių nuotraukų serijoje rodoma sugeneruota dokumentacija, pradedant nuo pagrindinio puslapio, po kurio seka puslapis „DefaultPackage“ (tingiai palikau scenarijų, „Groovy“ klases ir „Java“ klases dabartiniame kataloge ir be jokių paketų deklaracijų), o po jų - atitinkamai išvestis „Groovy“ scenarijui, „Groovy“ klasės pavyzdžiui ir sugalvotai „Java“ klasei. Paskutiniai trys vaizdai padeda atskirti „Groovy“ scenarijaus išvestį nuo „Groovy“ klasės ir „Java“ klasės išvestį.
„Groovydoc“ pagrindinio puslapio pavyzdys
„Groovydoc“ išvestis pavyzdiniam paketui („DefaultPackage“)
Groovydoc scenarijaus pavyzdžio išvestis
Groovydoc produkcija Groovy klasės pavyzdžiui
Groovydoc „Java“ pavyzdžio išvestis
Iš aukščiau pateiktos Groovydoc produkcijos galima padaryti keletą stebėjimų. Pirma, sukurta „Groovy“ scenarijaus dokumentacija dokumentavo tik scenarijuje apibrėžtus metodus (įskaitant numanomą pagrindinis metodas). Kas nėra taip akivaizdu iš aukščiau pateiktų statinių vaizdų, yra tai, kad iš tikrųjų scenarijams iš viso nėra sukurta „Groovydoc“ išvestis, nebent scenarijuje būtų aiškiai apibrėžtas bent vienas metodas. Jei scenarijuje apibrėžtas vienas metodas, tada „Groovydoc“ išvestis sukuriama bet kuriam apibrėžtam metodui ir numanomam pagrindiniam metodui. Variantas -nomininiai forskriptai gali būti perduotas „Groovydoc“, kad nebūtų sukurtas „Groovydoc“ numanomam pagrindinis metodas. Toliau rodoma šios parinkties pridėjimo išvestis (atkreipkite dėmesį, kad pagrindinisdokumentai nebėra rodomi).
-nommainforskriptai variantas yra gražus, nes mes dažnai nenorime pagrindinis funkcija yra netiesiogiai dokumentuota mūsų scenarijams. Iš tiesų pagrindinis funkcija paprastai yra „paslėpta“ nuo mūsų, kaip scenarijaus autorių ir palaikytojų.
Antras pastebėjimas, žiūrint į „Groovydoc“ sugeneruotą išvestį, yra tas, kad sukurta išvestis skiria „Groovy“ ir „Java“ šaltinio kodus. „Groovy“ scenarijai ir klasės pažymėti „[Groovy]“, o „Java“ klasės - „[Java]“. Tai taip pat akivaizdu „Groovydoc“ sugeneruotoje „Groovy API“ dokumentacijoje, kur dėl šių funkcijų lengva nustatyti, kad groovy.sql.Sql ir AntBuilder yra „Java“ klasės, o „JmxBuilder“ ir „SwingBuilder“ yra „Groovy“ klasės.
