Groovydoc tika ieviests 2007. gadā, lai sniegtu Groovy to, ko Javadoc nodrošina Java. Groovydoc tiek izmantots API dokumentācijas ģenerēšanai Groovy un Java klasēm, kas veido Groovy valodu. Šajā ziņojumā es aplūkoju Groovydoc izsaukšanu, izmantojot komandrindu un izmantojot Groovy sniegto pielāgoto Ant uzdevumu.
Groovy un Java pirmkods ar Groovydoc / Javadoc komentāriem
Lai parādītu Groovydoc, es izmantošu pielāgotas Groovy skripta un nodarbību versijas, kas vispirms tika ieviestas manā emuāra ziņā Easy Groovy Logger Injection and Log Guarding. Galvenais Groovy scenārijs un Groovy klases no šī ieraksta ir pārveidoti, lai iekļautu vairāk Javadoc stila komentāru, lai labāk parādītu Groovydoc darbībā. Pārskatītais skripts un saistītās klases tiek parādītas nākamajos kodu sarakstos.
demoGroovyLogTransformation.groovy
#! / usr / bin / lv groovy / ** * demoGroovyLogTransformation.groovy * * Grab SLF4J, Log4j un Apache Commons Logging atkarības, izmantojot @Grab un * demonstrē Groovy 1.8 injicētos mežizstrādes rokturus. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Nav nepieciešams "sagrābt" java.util.logging: tā ir daļa no JDK! / * * Norādot “slf4j-simple”, nevis “slf4j-api”, lai izvairītos no kļūdas * “Neizdevās ielādēt klasi” org.slf4j.impl.StaticLoggerBinder, kuru izraisa * nenorādot vai vairāk kā vienu no faktiskās reģistrēšanas iesiešanas bibliotēkas * lietošanai (sk. //www.slf4j.org/codes.html#StaticLoggerBinder). Viens jāizvēlas * no “slf4j-nop”, “slf4j-simple”, “slf4j-log4j12.jar”, * “slf4j-jdk14” vai “logback-classic”. Piemērs SLF4J * atkarības norādīšanai, izmantojot @Grab, ir pieejams vietnē * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Log4j atkarības norādīšanas, izmantojot @Grab, piemērs ir * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Piemērs Apache Commons reģistrēšanas atkarības norādīšanai, izmantojot @Grab, ir vietnē * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Palaidiet 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 = jauns ApacheCommonsLogger * nodrošināts ** ApacheCommonsLogger . * * @param textForHeader Teksts, kas jāiekļauj galvenē. * @param sizeOfHeader Rakstzīmju skaits katrā galvenes rindā. * / def printHeader (final String textForHeader, final int sizeOfHeader) {println "=". reizināt (sizeOfHeader) println "= $ {textForHeader} $ {'' .multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
importēt groovy.util.logging.Log / ** * Groovy klases paraugs, izmantojot {@code @Log}, lai ievadītu klasē java.util.logging logger *. * / @Log klase JavaUtilLoggerClass {/ ** * Konstruktors. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Izdrukājiet norādīto vērtību un pēc tam atgrieziet to kā daļu no virknes, kas norāda JDK java.util.logging daļu *. * * @param newValue Drukājamā vērtība, kas jāiekļauj atgriešanās virknē. * @return virkne, kas norāda newValue un JDK java.util.logging. * / public string printAndReturnValue (int newValue) {println "JDK: Drukas metode izsaukta $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
importēt groovy.util.logging.Log4j importēt org.apache.log4j.Level / ** * Groovy klases paraugs, izmantojot {@code @ Log4j}, lai ievadītu Log4j reģistrētāju * klasē. * / @ Log4j klase Log4jLoggerClass {/ ** * Konstruktors. * / Log4jLoggerClass () {// Šeit ir jāiestata reģistrēšanas līmenis, jo noklusējums ir FATAL un // šajā log.setLevel (Level.INFO) println "Log nJ Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Druka paredzēta vērtību un pēc tam atgrieziet to kā daļu no virknes, kas norāda Log4j daļu *. * * @param newValue Drukājamā vērtība, kas jāiekļauj atgriešanās virknē. * @return virkne, kas norāda newValue un Log4j. * / public string printAndReturnValue (int newValue) {println "Log4j: Drukas metode izsaukta $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
importējiet groovy.util.logging.Slf4j / ** * Groovy klases paraugs, izmantojot {@code @ Slf4j}, lai klasē injicētu vienkāršu reģistrēšanas fasādi * Java (SLF4J) reģistrētājam. * / @ Slf4j klase Slf4jLoggerClass {/ ** * Konstruktors. * / public Slf4jLoggerClass () {println "\ nSLF4J reģistrēšana ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {this .printAndReturnValue (2)} "} / ** * Izdrukājiet norādīto vērtību un pēc tam atgrieziet to kā daļu no virknes norādošās daļas * SLF4J reģistrēšanā. * * @param newValue Drukājamā vērtība, kas jāiekļauj atgriešanās virknē. * @return virkne, kas norāda newValue un SLF4J. * / public string printAndReturnValue (int newValue) {println "SLF4J: Drukas metode izsaukta $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
importēt groovy.util.logging.Commons / ** * Groovy klases paraugs, izmantojot {@code @Commons}, lai ievadītu Apache Commons reģistrētāju * klasē. * / @Commons klase ApacheCommonsLoggerClass {/ ** * Konstruktors. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons reģistrēšana ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Izdrukājiet norādīto vērtību un pēc tam atgrieziet to kā daļu no Apache Commons Logging virknes norādošās daļas *. * * @param newValue Drukājamā vērtība, kas jāiekļauj atgriešanās virknē. * @return virkne, kas norāda newValue un Apache Commons reģistrēšanu. * / public string printAndReturnValue (int newValue) {println "Commons: Drukas metode izsaukta $ {newValue}" return "Commons: $ {newValue}"}} Papildus iepriekš minētajam Groovy skriptam un klasēm es šeit izmantoju arī jaunu Java klasi, lai ilustrētu, ka Groovydoc darbojas gan Java, gan Groovy klasēs. Java klase nedara neko daudz, izņemot to, ka sniedz Džavadoka komentārus, kas jāapstrādā Groovydoc.
DoNothingClass.java
/ ** * Klase, kas neko nedara, bet šeit ir Java klase, kas darbojas caur * groovydoc. * / public class DoNothingClass {/ ** * Vienkārša metode, kas atgriež burtiski "Sveiki _adreses__!" virkne, kur * _addressee_ ir šai metodei piešķirtais nosaukums. * * @param adresāts Nosaukums atgrieztajam sveicienam, kas adresējams. * @return "Sveiki!" * / public String sayHello (galīgais virknes adresāts) {return "Labdien" + adresāts; } / ** * Galvenā izpildāmā funkcija. * / public static void main (pēdējie virknes [] argumenti) {final DoNothingClass me = new DoNothingClass (); me.sayHello ("Dastin"); } / ** * Norādiet virkni šim objektam. * * @return Stīgu attēlojums man. * / @Orride public String toString () {return "Sveiki!"; }} Darbojas Groovydoc komandrindā
Tā kā iepriekš parādītie Groovy skripts, Groovy klases un Java klase ir gatavi darbam, ir pienācis laiks pievērst uzmanību Groovydoc darbināšanai pret šīm klasēm un skriptu. Tāpat kā gadījumā ar Javadoc, Groovydoc var palaist no komandrindas. Komanda Groovydoc palaišanai pret iepriekš minētajām klasēm un skriptiem (pieņemot, ka tie visi atrodas tajā pašā direktorijā, kurā darbojas komanda) izskatās apmēram šādi:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -indowtitle "Groovy 1.8 mežizstrādes piemērs"-header "Groovy 1.8 mežizstrāde (iedvesmojoties no faktiskajiem notikumiem)" -pēdiņa "Iedvesmojoties no faktiskajiem notikumiem: pieteikšanās Groovy 1.8 "-doctitle" Mežizstrāde pakalpojumā Groovy 1.8 Demonstrated "* .groovy * .java Iepriekš minētā komanda tiek palaista vienā rindā. Tomēr, lai uzlabotu lasāmību, esmu pievienojis rindiņu pārtraukumus, lai komandu sadalītu.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -indowtitle "Groovy 1.8 mežizstrādes piemērs"-header "Groovy 1.8 mežizstrāde (iedvesmojoties no faktiskajiem notikumiem)" -pēderis "Iedvesmojoties no faktiskajiem notikumiem: pieteikšanās Groovy 1.8 "-doctitle" Mežizstrāde pakalpojumā Groovy 1.8 Demonstrated "* .groovy * .java Groovydoc komandas parametri izskatās pazīstami ikvienam, kurš ir lietojis javadoc no komandrindas. Komandas pēdējā daļa norāda, ka groovydoc ir jāpalaiž pret Groovy un Java kodu.
Skrien Groovydoc no Ant
Groovydoc var arī viegli piekļūt, izmantojot pielāgotu Ant uzdevumu, kā aprakstīts Groovy lietotāja rokasgrāmatā. Ir diezgan viegli piemērot groovydoc Ant uzdevumu, vispirms izveidojot atbilstošo taskdef un pēc tam izmantojot šo definēto tagu. Tas ir parādīts nākamajā atbilstošā XML fragmentā build.xml failu.
Skudru build.xml faila daļas, kas parāda groovydoc uzdevumu
Skudras daļa build.xml parādīts iepriekš, ir aptuveni līdzvērtīgs komandrindā izmantotajam. Ir svarīgi, lai Groovydoc būtu pieejams caur Ant, jo tas atvieglo Groovy dokumentācijas veidošanu no Ant balstītām būvēšanas sistēmām.
Groovydoc ģenerētā dokumentācija
Tā kā katra pieeja Groovy dokumentācijas ģenerēšanai, izmantojot Groovydoc (komandrindas vai balstītas uz Ant), darbojas apmēram tāpat kā otra, es tagad pievērsīšos HTML izejai, kas varētu rasties no jebkuras pieejas. Nākamajā ekrāna momentuzņēmumu sērijā tiek parādīta ģenerētā dokumentācija, kas sākas ar galveno lapu, kam seko lapa DefaultPackage (es slinki atstāju skriptu, Groovy klases un Java klasi pašreizējā direktorijā un bez paketes deklarācijas), kam seko attiecīgi izeja par Groovy skriptu, par Groovy klases piemēru un par izdomāto Java klasi. Trīs pēdējie attēli palīdz atšķirt Groovy Script izeju no Groovy klases un Java klasi.
Groovydoc galvenās lapas piemērs
Groovydoc izvade paketes paraugam (DefaultPackage)
Groovydoc izvade Groovy skripta piemēram
Groovydoc produkcija Groovy klases piemēram
Groovydoc izvade Java klases paraugam
No iepriekš redzamās Groovydoc izejas var veikt vairākus novērojumus. Pirmkārt, Groovy skripta izveidotā dokumentācija dokumentēja tikai skriptā noteiktās metodes (ieskaitot netiešo galvenais metode). Kas nav tik acīmredzams no iepriekš redzamajiem statiskajiem attēliem, ir tas, ka faktiski skriptam vispār netiek izveidota Groovydoc izeja, ja vien skriptā nav skaidri definēta vismaz viena metode. Ja skriptā ir definēta viena metode, tad jebkurai definētai metodei un netiešajai galvenajai metodei tiek ģenerēta Groovydoc izeja. Variants -nomensforscripts var nodot Groovydoc, lai netiešajam netiktu ģenerēts Groovydoc galvenais metodi. Nākamais tiek parādīts šīs opcijas pievienošanas rezultāts (ņemiet vērā, ka galvenaisdokumentācija vairs netiek rādīta).
The -nommainforscript opcija ir jauka, jo mēs bieži nevēlamies galvenais funkcija ir netieši dokumentēta mūsu skriptiem. Patiešām, galvenais Funkcija parasti ir "paslēpta" no mums kā skriptu rakstītājiem un uzturētājiem.
Otrais novērojums, aplūkojot Groovydoc ģenerēto izvadi, ir tāds, ka ģenerētais produkts izšķir Groovy un Java avota kodu. Groovy skripti un klases ir apzīmēti ar "[Groovy]" un Java klases ir apzīmēti ar "[Java]". Tas ir redzams arī Groovydoc ģenerētajā Groovy API dokumentācijā, kur šīs funkcijas ļauj viegli noteikt, ka groovy.sql.Sql un AntBuilder ir Java klases, bet JmxBuilder un SwingBuilder ir Groovy klases.
