Το Groovydoc εισήχθη το 2007 για να παρέχει στον Groovy αυτό που παρέχει ο Javadoc για την Java. Το Groovydoc χρησιμοποιείται για τη δημιουργία τεκμηρίωσης API για τις τάξεις Groovy και Java που συνθέτουν τη γλώσσα Groovy. Σε αυτήν την ανάρτηση, εξετάζω την επίκληση του Groovydoc μέσω της γραμμής εντολών και μέσω της προσαρμοσμένης εργασίας του Ant Groovy.
Πηγαίος κώδικας Groovy και Java με σχόλια Groovydoc / Javadoc
Θα χρησιμοποιήσω προσαρμοσμένες εκδόσεις του σεναρίου και των τάξεων του Groovy που παρουσιάστηκαν για πρώτη φορά στην ανάρτηση ιστολογίου μου Easy Groovy Logger Injection και Log Guarding για να δείξω το Groovydoc. Το κύριο σενάριο Groovy και οι τάξεις του Groovy από αυτήν την ανάρτηση έχουν τροποποιηθεί ώστε να περιλαμβάνουν περισσότερα σχόλια σε στυλ Javadoc για να αποδεικνύουν καλύτερα τον Groovydoc σε δράση. Το αναθεωρημένο σενάριο και οι σχετικές τάξεις εμφανίζονται στις επόμενες καταχωρίσεις κώδικα.
demoGroovyLogTransformation.groovy
#! / usr / bin / env groovy / ** * demoGroovyLogTransformation.groovy * * Grab SLF4J, Log4j και Apache Commons Logging εξαρτήσεις χρησιμοποιώντας το @Grab και * επιδείξτε τις λαβές καταγραφής Groovy 1.8. * * //marxsoftware.blogspot.com/2011/05/easy-groovy-logger-injection-an ... * / // Δεν χρειάζεται να "αρπάξετε" java.util.logging: είναι μέρος του JDK! / * * Καθορισμός του "slf4j-simple" αντί του "slf4j-api" για να αποφευχθεί το σφάλμα * "Αποτυχία φόρτωσης κλάσης" org.slf4j.impl.StaticLoggerBinder "που προκαλείται από * τον καθορισμό όχι ή περισσότερων από ένα από τα πραγματικά αρχεία καταγραφής δεσμευτικές βιβλιοθήκες * που θα χρησιμοποιηθούν (βλ. //www.slf4j.org/codes.html#StaticLoggerBinder). Κάποιος πρέπει * να επιλεγεί από «slf4j-nop», «slf4j-simple», «slf4j-log4j12.jar», * "slf4j-jdk14" ή "logback-classic". Ένα παράδειγμα καθορισμού της εξάρτησης SLF4J * μέσω @Grab είναι διαθέσιμο στη διεύθυνση * //mvnrepository.com/artifact/org.slf4j/slf4j-api/1.6.1. * / @Grab (group = 'org.slf4j', module = "slf4j-simple", version = "1.6.1") / * * Ένα παράδειγμα καθορισμού της εξάρτησης Log4j μέσω @Grab βρίσκεται στη διεύθυνση * //mvnrepository.com/artifact /log4j/log4j/1.2.16. * / @Grab (group = 'log4j', module = "log4j", version = "1.2.16") / * * Ένα παράδειγμα καθορισμού της εξάρτησης Apache Commons Logging μέσω του @Grab είναι στο * //mvnrepository.com/artifact/commons-logging/commons-logging-api/1 ..... * / @Grab (group = 'commons-logging', module = "commons-loggin g-api ", version =" 1.1 ") / * * Εκτελέστε τις δοκιμές ... * / 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 = new ApacheCommonsLogger . * * @param textForHeader Κείμενο που θα συμπεριληφθεί στην κεφαλίδα. * @param sizeOfHeader Αριθμός χαρακτήρων σε κάθε σειρά κεφαλίδας. * / def printHeader (final String textForHeader, final int sizeOfHeader) {println "=". multiply (sizeOfHeader) println "= $ {textForHeader} $ {" ".multiply (sizeOfHeader-textForHeader.size () - 4)} =" .multiply (sizeOfHeader)} JavaUtilLoggerClass.groovy
εισαγωγή groovy.util.logging.Log / ** * Δείξτε την τάξη του Groovy χρησιμοποιώντας το {@code @Log} για να κάνετε ένεση του java.util.logging logger * στην τάξη. * / @Log class JavaUtilLoggerClass {/ ** * Κατασκευαστής. * / public JavaUtilLoggerClass () {println "\ njava.util.logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.finer " $ {this.printAndReturnValue (2)} "} / ** * Εκτυπώστε την παρεχόμενη τιμή και, στη συνέχεια, επιστρέψτε την ως μέρος της συμβολοσειράς, υποδεικνύοντας μέρος * του java.util.logging του JDK. * * @param newValue Αξία που θα εκτυπωθεί και θα συμπεριληφθεί στο String Return. * @return String που δείχνει newValue και JDK για java.util.logging. * / public String printAndReturnValue (int newValue) {println "JDK: Η μέθοδος εκτύπωσης κλήθηκε για $ {newValue}" return "JDK: $ {newValue}"}} Log4jLoggerClass.groovy
import groovy.util.logging.Log4j import org.apache.log4j.Level / ** * Δείγμα κλάσης Groovy χρησιμοποιώντας το {@code @ Log4j} για να εισαγάγει το Log4j logger * στην τάξη. * / @ Log4j class Log4jLoggerClass {/ ** * Κατασκευαστής. * / Log4jLoggerClass () {// Είναι απαραίτητο να ορίσετε το επίπεδο καταγραφής εδώ επειδή η προεπιλογή είναι FATAL και // δεν χρησιμοποιούμε αρχείο εξωτερικής διαμόρφωσης Log4j σε αυτό το παράδειγμα log.setLevel (Level.INFO) println "\ nLog4j Logging ($ {log.name}: $ {log.class}): "log.info" $ {this.printAndReturnValue (1)} "log.debug" $ {this.printAndReturnValue (2)} "} / ** * Παρέχεται εκτύπωση τιμή και, στη συνέχεια, επιστρέψτε το ως μέρος της συμβολοσειράς που δείχνει το μέρος * του Log4j * * @param newValue Αξία που θα εκτυπωθεί και θα συμπεριληφθεί στο String Return. * @return String που δείχνει newValue και Log4j. * / public String printAndReturnValue (int newValue) {println "Log4j: Η μέθοδος εκτύπωσης κλήθηκε για $ {newValue}" return "Log4j: $ {newValue}"}} Slf4jLoggerClass.groovy
εισαγωγή groovy.util.logging.Slf4j / ** * Δείξτε την τάξη του Groovy χρησιμοποιώντας το {@code @ Slf4j} για να εισάγετε το Simple Logging Facade για τον καταγραφέα * Java (SLF4J) στην τάξη. * / @ Slf4j class Slf4jLoggerClass {/ ** * Κατασκευαστής. * / public Slf4jLoggerClass () {println "\ nSLF4J Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ {αυτό .printAndReturnValue (2)} "} / ** * Εκτυπώστε την παρεχόμενη τιμή και, στη συνέχεια, επιστρέψτε την ως μέρος της συμβολοσειράς που υποδεικνύει μέρος * της καταγραφής SLF4J. * * @param newValue Αξία που θα εκτυπωθεί και θα συμπεριληφθεί στο String Return. * @return String που δείχνει newValue και SLF4J. * / public String printAndReturnValue (int newValue) {println "SLF4J: Η μέθοδος εκτύπωσης κλήθηκε για $ {newValue}" return "SLF4J: $ {newValue}"}} ApacheCommonsLoggerClass.groovy
import groovy.util.logging.Commons / ** * Δείξτε την τάξη του Groovy χρησιμοποιώντας το {@code @Commons} για να κάνετε ένεση του καταγραφικού Apache Commons * στην τάξη. * / @Commons class ApacheCommonsLoggerClass {/ ** * Κατασκευαστής. * / public ApacheCommonsLoggerClass () {println "\ nApache Commons Logging ($ {log.name}: $ {log.class}):" log.info "$ {this.printAndReturnValue (1)}" log.debug "$ { this.printAndReturnValue (2)} "} / ** * Εκτυπώστε την παρεχόμενη τιμή και, στη συνέχεια, επιστρέψτε την ως μέρος της συμβολοσειράς που υποδεικνύει το μέρος * της καταγραφής Apache Commons. * * @param newValue Αξία που θα εκτυπωθεί και θα συμπεριληφθεί στο String Return. * @return String που δείχνει καταγραφή newValue και Apache Commons. * / public String printAndReturnValue (int newValue) {println "Commons: Η μέθοδος εκτύπωσης κλήθηκε για $ {newValue}" return "Commons: $ {newValue}"}} Εκτός από το παραπάνω σενάριο και τάξεις του Groovy, χρησιμοποιώ επίσης μια νέα τάξη Java εδώ για να δείξω ότι το Groovydoc λειτουργεί σε τάξεις Java καθώς και σε τάξεις Groovy. Η τάξη Java δεν κάνει πολλά εκτός από την παροχή των σχολίων Javadoc για επεξεργασία από τον Groovydoc.
DoNothingClass.java
/ ** * Τάξη που δεν κάνει τίποτα, αλλά είναι εδώ για να είναι μια τάξη Java που εκτελείται μέσω του * groovydoc. * / δημόσια τάξη DoNothingClass {/ ** * Απλή μέθοδος που επιστρέφει κυριολεκτικά "Γεια σας _addressee_!" string όπου * _addressee_ είναι το όνομα που παρέχεται σε αυτήν τη μέθοδο. * * @param addressee Όνομα για τον επιστρεφόμενο χαιρετισμό στον οποίο θα απευθυνθείτε. * @return "Γεια!" * / public String sayHello (τελικός παραλήπτης συμβολοσειράς) {return "Hello," + addressee; } / ** * Κύρια εκτελέσιμη λειτουργία. * / public static void main (final επιχειρήματα String []) {final DoNothingClass me = νέο DoNothingClass (); me.sayHello ("Dustin"); } / ** * Παρέχετε την παράσταση συμβολοσειράς αυτού του αντικειμένου. * * @return String εκπροσώπηση μου. * / @ Override public String toString () {return "Γεια!"; }} Εκτέλεση του Groovydoc στη γραμμή εντολών
Με το σενάριο Groovy, τα μαθήματα Groovy και την κλάση Java που εμφανίζονται παραπάνω έτοιμα να ξεκινήσουν, είναι καιρός να στρέψετε την προσοχή στην εκτέλεση του Groovydoc σε αυτές τις τάξεις και σενάρια. Όπως συμβαίνει με το Javadoc, το Groovydoc μπορεί να εκτελεστεί από τη γραμμή εντολών. Η εντολή για την εκτέλεση του Groovydoc με τις παραπάνω κατηγορίες και σενάρια (υποθέτοντας ότι είναι όλα στον ίδιο κατάλογο στον οποίο εκτελείται η εντολή) μοιάζει με αυτό:
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "Groovy 1.8 Παράδειγμα καταγραφής" -header "Groovy 1.8 Logging (Εμπνευσμένο από τα πραγματικά γεγονότα)" -footer "Εμπνευσμένο από τα πραγματικά γεγονότα: Σύνδεση στο Groovy 1.8 "-doctitle" Σύνδεση στο Groovy 1.8 Επίδειξη "* .groovy * .java Η παραπάνω εντολή εκτελείται σε μία γραμμή. Ωστόσο, για βελτιωμένη αναγνωσιμότητα, έχω προσθέσει αλλαγές γραμμής για να σπάσω την εντολή.
groovydoc -classpath C: \ groovy-1.8.0 \ lib \ -d output -windowtitle "Groovy 1.8 Παράδειγμα καταγραφής" -header "Groovy 1.8 Logging (Εμπνευσμένο από τα πραγματικά γεγονότα)" -footer "Εμπνευσμένο από τα πραγματικά γεγονότα: Σύνδεση στο Groovy 1.8 "-doctitle" Σύνδεση στο Groovy 1.8 Επίδειξη "* .groovy * .java Οι παράμετροι της εντολής groovydoc φαίνονται οικείες σε όποιον έχει χρησιμοποιήσει το javadoc από τη γραμμή εντολών. Το τελευταίο μέρος της εντολής καθορίζει ότι το groovydoc πρέπει να εκτελείται έναντι του κώδικα Groovy και Java.
Εκτέλεση Groovydoc από Ant
Η πρόσβαση στο Groovydoc είναι επίσης εύκολη μέσω μιας προσαρμοσμένης εργασίας Ant όπως περιγράφεται στον Οδηγό χρήσης του Groovy. Είναι αρκετά εύκολο να εφαρμόσετε το groovydoc Ant task ρυθμίζοντας πρώτα το κατάλληλο taskdef και στη συνέχεια χρησιμοποιώντας αυτήν την καθορισμένη ετικέτα. Αυτό φαίνεται στο παρακάτω απόσπασμα XML από σχετικό build.xml αρχείο.
Τμήματα ενός αρχείου Ant build.xml που δείχνει την εργασία groovydoc
Το τμήμα του μυρμηγκιού build.xml φαίνεται παραπάνω είναι περίπου ισοδύναμο με αυτό που χρησιμοποιείται στη γραμμή εντολών. Η διαθεσιμότητα του Groovydoc μέσω Ant είναι σημαντική επειδή διευκολύνει την ενσωμάτωση της δημιουργίας τεκμηρίωσης του Groovy από συστήματα κατασκευής που βασίζονται σε Ant.
Τεκμηρίωση που δημιουργήθηκε από το Groovydoc
Επειδή κάθε προσέγγιση για τη δημιουργία τεκμηρίωσης του Groovy μέσω του Groovydoc (γραμμή εντολών ή με βάση το Ant) λειτουργεί σχεδόν το ίδιο με το άλλο, τώρα θα επικεντρωθώ στην έξοδο HTML που θα μπορούσε να προέλθει από οποιαδήποτε από τις δύο μεθόδους. Η επόμενη σειρά στιγμιότυπων οθόνης δείχνει την παραγόμενη τεκμηρίωση ξεκινώντας από την κύρια σελίδα, ακολουθούμενη από τη σελίδα DefaultPackage (άφησα τεμπέλης το σενάριο, τις τάξεις Groovy και την τάξη Java στον τρέχοντα κατάλογο και χωρίς καμία δήλωση πακέτου), ακολουθούμενη αντίστοιχα από την έξοδο για το σενάριο Groovy, για παράδειγμα Groovy class και για την επινοημένη κλάση Java. Οι τρεις τελευταίες εικόνες βοηθούν στη διάκριση μεταξύ της εξόδου για ένα σενάριο Groovy έναντι μιας κατηγορίας Groovy έναντι μιας κλάσης Java.
Παράδειγμα κύριας σελίδας Groovydoc
Έξοδος Groovydoc για παράδειγμα πακέτο (DefaultPackage)
Έξοδος Groovydoc για παράδειγμα Groovy Script
Έξοδος Groovydoc για παράδειγμα Groovy Class
Έξοδος Groovydoc για παράδειγμα Java Class
Αρκετές παρατηρήσεις μπορούν να γίνουν από την έξοδο Groovydoc που φαίνεται παραπάνω. Πρώτον, η τεκμηρίωση που δημιουργήθηκε για το σενάριο Groovy τεκμηρίωσε μόνο τις μεθόδους που ορίζονται στο σενάριο (συμπεριλαμβανομένου του σιωπηρού κύριος μέθοδος). Αυτό που δεν είναι τόσο προφανές από τις παραπάνω στατικές εικόνες είναι ότι, στην πραγματικότητα, δεν δημιουργείται καθόλου έξοδος Groovydoc για ένα σενάριο, εκτός εάν τουλάχιστον μια μέθοδος ορίζεται ρητά στο σενάριο. Εάν μια μέθοδος ορίζεται στο σενάριο, τότε δημιουργείται έξοδος Groovydoc για οποιεσδήποτε καθορισμένες μεθόδους και για την έμμεση κύρια μέθοδο. Η επιλογή -κατά γραφή μπορεί να περάσει στο Groovydoc για να μην δημιουργηθεί Groovydoc για το σιωπηρό κύριος μέθοδος. Το αποτέλεσμα της προσθήκης αυτής της επιλογής εμφανίζεται στη συνέχεια (σημειώστε ότι το κύριοςΗ τεκμηρίωση δεν εμφανίζεται πλέον).
ο -συμπληρωματικά σενάρια Η επιλογή είναι ωραία γιατί συχνά δεν θέλουμε το κύριος λειτουργία για να τεκμηριώνονται σιωπηρά για τα σενάρια μας. Πράγματι, το κύριος Η λειτουργία είναι συνήθως "κρυφή" από εμάς ως συγγραφείς σεναρίων και συντηρητές.
Μια δεύτερη παρατήρηση από την εξέταση της παραγωγής που παράγεται από το Groovydoc είναι ότι η παραγόμενη έξοδος διακρίνει μεταξύ του πηγαίου κώδικα Groovy και Java. Τα σενάρια και οι τάξεις του Groovy φέρουν την ετικέτα "[Groovy]" και οι τάξεις Java φέρουν την ετικέτα "[Java]." Αυτό είναι επίσης εμφανές στην τεκμηρίωση Groovy API που δημιουργείται από το Groovydoc, όπου αυτές οι δυνατότητες διευκολύνουν τον εντοπισμό ότι οι groovy.sql.Sql και AntBuilder είναι κλάσεις Java, ενώ οι JmxBuilder και SwingBuilder είναι τάξεις Groovy
