what is javadoc how use it generate documentation
Αυτό το σεμινάριο εξηγεί τι είναι το εργαλείο JavaDoc και τα σχόλια και οι μέθοδοι JavaDoc για τη δημιουργία τεκμηρίωσης κώδικα:
Το JavaDoc είναι ένα ειδικό εργαλείο που συσκευάζεται με το JDK. Χρησιμοποιείται για τη δημιουργία της τεκμηρίωσης κώδικα του πηγαίου κώδικα Java σε μορφή HTML.
Είναι μια γεννήτρια τεκμηρίωσης για τη γλώσσα Java από την Sun Microsystems (σήμερα Oracle Corporation).
=> Ελέγξτε ΟΛΑ τα Εκπαιδευτικά Java εδώ.
Τι θα μάθετε:
Τι είναι το JavaDoc
Αυτό το εργαλείο χρησιμοποιεί τη μορφή 'σχόλια εγγράφων' για την τεκμηρίωση τάξεων Java. Τα IDE όπως το Eclipse, το IntelliJIDEA ή το NetBeans διαθέτουν ένα ενσωματωμένο εργαλείο JavaDoc για τη δημιουργία τεκμηρίωσης HTML. Έχουμε επίσης πολλούς επεξεργαστές αρχείων στην αγορά που μπορούν να βοηθήσουν τον προγραμματιστή να παράγει πηγές JavaDoc.
Εκτός από την τεκμηρίωση του πηγαίου κώδικα, αυτό το εργαλείο παρέχει επίσης API που δημιουργεί 'doclets' και 'taglets' που χρησιμοποιούμε για την ανάλυση της δομής μιας εφαρμογής Java.
Ένα σημείο που πρέπει να σημειωθεί είναι ότι αυτό το εργαλείο δεν επηρεάζει με κανέναν τρόπο την απόδοση της εφαρμογής καθώς ο μεταγλωττιστής αφαιρεί όλα τα σχόλια κατά τη σύνταξη του προγράμματος Java.
Η σύνταξη σχολίων στο πρόγραμμα και στη συνέχεια η χρήση του JavaDoc για τη δημιουργία της τεκμηρίωσης είναι να βοηθήσει τον προγραμματιστή / χρήστη να κατανοήσει τον κώδικα.
Η τεκμηρίωση HTML που δημιουργείται από το JavaDoc είναι τεκμηρίωση API. Αναλύει τις δηλώσεις και δημιουργεί ένα σύνολο αρχείων προέλευσης. Το αρχείο προέλευσης περιγράφει πεδία, μεθόδους, κατασκευαστές και τάξεις.
Σημειώστε ότι προτού χρησιμοποιήσουμε το εργαλείο JavaDoc στον πηγαίο κώδικα, πρέπει να συμπεριλάβουμε ειδικά προγράμματα JavaDoc στο πρόγραμμα.
Ας προχωρήσουμε τώρα στα σχόλια.
Σχόλια JavaDoc
Η γλώσσα Java υποστηρίζει τους ακόλουθους τύπους σχολίων.
# 1) Σχόλια μιας γραμμής: Το σχόλιο μίας γραμμής συμβολίζεται με « // 'Και όταν ο μεταγλωττιστής συναντά αυτά, αγνοεί ό, τι ακολουθεί αυτά τα σχόλια μέχρι το τέλος της γραμμής.
# 2) Πολλαπλά σχόλια: Τα πολλαπλά σχόλια παρουσιάζονται χρησιμοποιώντας το « /*….*/ '. Έτσι, όταν συναντήσετε την ακολουθία ‘/ *’, ο μεταγλωττιστής αγνοεί όλα όσα ακολουθούν αυτήν την ακολουθία έως ότου συναντήσει την ακολουθία κλεισίματος ‘* /’.
# 3) Σχόλια τεκμηρίωσης: Αυτά ονομάζονται σχόλια Doc και χρησιμοποιούνται από το εργαλείο για τη δημιουργία τεκμηρίωσης API. Τα σχόλια του εγγράφου επισημαίνονται ως ' /** τεκμηρίωση */ '. Όπως μπορούμε να δούμε, αυτά τα σχόλια διαφέρουν από τα κανονικά σχόλια που περιγράφονται παραπάνω. Τα σχόλια του εγγράφου μπορεί επίσης να περιέχουν ετικέτες HTML μέσα τους, όπως θα δούμε σύντομα.
τι είναι ένα αρχείο json πώς να ανοίξετε
Επομένως, για να δημιουργήσουμε τεκμηρίωση API χρησιμοποιώντας αυτό το εργαλείο, πρέπει να παρέχουμε αυτά τα σχόλια τεκμηρίωσης (σχόλια εγγράφων) στο πρόγραμμά μας.
Δομή ενός σχολίου JavaDoc
Η δομή του σχολίου του Doc στην Java είναι παρόμοια με το multiline comment, εκτός από το ότι το σχόλιο του doc έχει έναν επιπλέον αστερίσκο (*) στην αρχική ετικέτα. Έτσι, το σχόλιο του εγγράφου ξεκινά με «/ **» αντί για «/ *».
Επιπλέον, τα σχόλια τύπου JavaDoc μπορούν επίσης να έχουν ετικέτες HTML μέσα σε αυτό.
Μορφή σχολίων JavaDoc
Με βάση τη δομή προγραμματισμού στην οποία θέλουμε να τεκμηριώσουμε, μπορούμε να τοποθετήσουμε σχόλια εγγράφων πάνω από οποιαδήποτε δομή όπως κλάση, μέθοδο, πεδίο κ.λπ. Ας δούμε παραδείγματα για κάθε ένα από τα σχόλια doc των κατασκευών.
Μορφή επιπέδου τάξης
Η μορφή σχολίων εγγράφων σε επίπεδο τάξης θα φαίνεται όπως φαίνεται παρακάτω:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Όπως φαίνεται παραπάνω, ένα σχόλιο εγγράφου σε επίπεδο τάξης θα έχει όλες τις λεπτομέρειες, συμπεριλαμβανομένου του συγγραφέα της τάξης, των συνδέσμων εάν υπάρχουν κ.λπ.
Μορφή επιπέδου μεθόδου
Δίνεται παρακάτω ένα παράδειγμα μορφής εγγράφου σε επίπεδο μεθόδου.
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } Όπως μπορούμε να δούμε από το παραπάνω παράδειγμα, μπορούμε να έχουμε οποιοδήποτε αριθμό ετικετών στο σχόλιο εγγράφου της μεθόδου. Μπορούμε επίσης να έχουμε παραγράφους μέσα στην περιγραφή σχολίων που υποδεικνύεται από
...
.Έχουμε επίσης ειδικές ετικέτες για να περιγράψουμε την τιμή επιστροφής (@return) και τις παραμέτρους της μεθόδου (@param).
Μορφή επιπέδου πεδίου
Το παρακάτω παράδειγμα δείχνει το σχόλιο του εγγράφου για ένα πεδίο.
/** * The public name of a message */ private String msg_txt;Όπως φαίνεται από το παραπάνω παράδειγμα, μπορούμε επίσης να έχουμε απλά σχόλια χωρίς ετικέτες. Σημειώστε ότι το JavaDoc δεν δημιουργεί τεκμηρίωση για ιδιωτικά πεδία, εκτός εάν καθορίσουμε μια ιδιωτική επιλογή με την εντολή JavaDoc.
Τώρα ας συζητήσουμε τις ετικέτες που χρησιμοποιούνται με τα σχόλια του εγγράφου.
Ετικέτες JavaDoc
Η Java παρέχει διάφορες ετικέτες που μπορούμε να συμπεριλάβουμε στο σχόλιο του εγγράφου. Όταν χρησιμοποιούμε αυτές τις ετικέτες, το εργαλείο αναλύει αυτές τις ετικέτες για να δημιουργήσει ένα καλά μορφοποιημένο API από τον πηγαίο κώδικα.
Κάθε ετικέτα έχει διάκριση πεζών-κεφαλαίων και ξεκινά με ένα σύμβολο «@». Κάθε ετικέτα ξεκινά στην αρχή της γραμμής όπως μπορούμε να δούμε από τα παραπάνω παραδείγματα. Διαφορετικά, ο μεταγλωττιστής το αντιμετωπίζει ως κανονικό κείμενο. Ως σύμβαση, οι ίδιες ετικέτες τοποθετούνται μαζί.
Υπάρχουν δύο τύποι ετικετών που μπορούμε να χρησιμοποιήσουμε στο σχόλιο του εγγράφου.
# 1) Αποκλεισμός ετικετών : Οι μπλοκ ετικέτες έχουν τη μορφή @tag_name .
Οι μπλοκ ετικέτες μπορούν να τοποθετηθούν στην ενότητα ετικετών και να ακολουθήσουν την κύρια περιγραφή .
# 2) Ενσωματωμένες ετικέτες :Οι ενσωματωμένες ετικέτες περικλείονται σε σγουρά τιράντες και έχουν τη μορφή, {@tag_name} . Οι ενσωματωμένες ετικέτες μπορούν να τοποθετηθούν οπουδήποτε μέσα στο σχόλιο του εγγράφου.
Στον παρακάτω πίνακα παρατίθενται όλες οι ετικέτες που μπορούν να χρησιμοποιηθούν στα σχόλια του εγγράφου.
| Ετικέτα | Περιγραφή | Εφαρμόζεται σε |
|---|---|---|
| @ επιστροφή περιγραφή | Παρέχει περιγραφή τιμής επιστροφής. | Μέθοδος |
| @author xyz | Υποδεικνύει τον συγγραφέα τάξης, διεπαφής ή enum. | Κατηγορία, διασύνδεση, Enum |
| {@docRoot} | Αυτή η ετικέτα έχει τη σχετική διαδρομή προς τον ριζικό κατάλογο του εγγράφου. | Κατηγορία, διεπαφή, Enum, Field, Method |
| Έκδοση @version | Καθορίζει την καταχώριση έκδοσης λογισμικού. | Κατηγορία, διασύνδεση, Enum |
| @since από το κείμενο | Καθορίζει από πότε υπάρχει αυτή η λειτουργικότητα | Κατηγορία, διεπαφή, Enum, Field, Method |
| @ ανατρέξτε στην αναφορά | Καθορίζει αναφορές (συνδέσμους) σε άλλα έγγραφα | Κατηγορία, διεπαφή, Enum, Field, Method |
| περιγραφή ονόματος @param | Χρησιμοποιείται για την περιγραφή της παραμέτρου / ορίσματος της μεθόδου. | Μέθοδος |
| @exception classname περιγραφή | Καθορίζει την εξαίρεση που μπορεί να χρησιμοποιήσει η μέθοδος στον κωδικό της. | Μέθοδος |
| @throws classname περιγραφή | ||
| @drecreated περιγραφή | Καθορίζει εάν η μέθοδος είναι παλιά | Κατηγορία, διασύνδεση, Enum, πεδίο, μέθοδος |
| {@inheritDoc} | Χρησιμοποιείται για την αντιγραφή της περιγραφής από την παράκαμψη της μεθόδου σε περίπτωση κληρονομιάς | Παράκαμψη μέθοδος |
| {@ σύνδεσμος αναφοράς} | Παρέχει αναφορές ή συνδέσμους σε άλλα σύμβολα. | Κατηγορία, διεπαφή, Enum, Field, Method |
| {@linkplain αναφορά} | Το ίδιο με το {@link} αλλά εμφανίζεται σε απλό κείμενο. | Κατηγορία, διεπαφή, Enum, Field, Method |
| {@value #STATIC_FIELD} | Περιγράψτε την τιμή ενός στατικού πεδίου. | Στατικό πεδίο |
| {@code literal} | Χρησιμοποιείται για τη μορφοποίηση του κυριολεκτικού κειμένου σε γραμματοσειρά κώδικα παρόμοια με το {@literal}. | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
ιστότοπους anime για παρακολούθηση δωρεάν anime
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } Γνωρίζουμε ότι δεν χρειάζεται να μεταγλωττίσουμε το πρόγραμμα ή το έργο για τη δημιουργία JavaDoc. Το IntelliJIdea Ide παρέχει ένα ενσωματωμένο εργαλείο για τη δημιουργία της τεκμηρίωσης. Ακολουθήστε τα παρακάτω βήματα για να δημιουργήσετε την τεκμηρίωση χρησιμοποιώντας το IntelliJIdea.
- Κάντε κλικ στο Εργαλεία -> Δημιουργία JavaDoc
- Η ακόλουθη οθόνη ανοίγει όταν κάνετε κλικ στο εργαλείο JavaDoc.
Εδώ μπορούμε να καθορίσουμε αν θέλουμε να δημιουργήσουμε τεκμηρίωση για ολόκληρο το έργο ή μόνο μία κλάση κ.λπ. Μπορούμε επίσης να καθορίσουμε τον κατάλογο εξόδου όπου θα δημιουργηθούν τα αρχεία τεκμηρίωσης. Υπάρχουν διάφορες άλλες προδιαγραφές όπως φαίνεται στο παραπάνω σχήμα.
Κάντε κλικ στο OK, αφού καθοριστούν όλες οι παράμετροι.
- Τώρα μπορούμε να δούμε τη διαδικασία δημιουργίας Java Doc στο παράθυρο εξόδου. Ένα δείγμα παραθύρου εξόδου Java Doc φαίνεται όπως φαίνεται παρακάτω:
- Μόλις ολοκληρωθεί η δημιουργία, δημιουργούνται τα ακόλουθα αρχεία.
- Όπως καθορίσαμε την κύρια κλάση, δημιουργείται το αρχείο Main.html. Σημειώστε ότι το index.html έχει επίσης το ίδιο περιεχόμενο με το Main.html.
- Το αρχείο help-doc.html περιέχει γενικούς ορισμούς των οντοτήτων Java. Ένα δείγμα περιεχομένου αυτού του αρχείου εμφανίζεται παρακάτω.
- Ομοίως, δίνεται παρακάτω είναι ένα δείγμα περιεχομένου στο αρχείο Main.html
Έτσι, αυτός είναι ο τρόπος με τον οποίο μπορούμε να δημιουργήσουμε τεκμηρίωση χρησιμοποιώντας αυτό το εργαλείο στην ιδέα του IntelliJ. Μπορούμε να ακολουθήσουμε παρόμοια βήματα σε άλλα Java IDE όπως το Eclipse και / ή το NetBeans.
Συχνές Ερωτήσεις
Q # 1) Ποια είναι η χρήση του JavaDoc;
Απάντηση: Το εργαλείο JavaDoc συνοδεύεται από JDK. Χρησιμοποιείται για τη δημιουργία της τεκμηρίωσης κώδικα για τον πηγαίο κώδικα Java σε μορφή HTML. Αυτό το εργαλείο απαιτεί τα σχόλια στον πηγαίο κώδικα να παρέχονται σε προκαθορισμένη μορφή ως /**….*/. Αυτά ονομάζονται επίσης σχόλια doc.
Q # 2) Ποιο είναι το παράδειγμα τεκμηρίωσης Java;
Απάντηση: Το εργαλείο τεκμηρίωσης εγγράφων Java δημιουργεί αρχεία HTML έτσι ώστε να μπορούμε να δούμε την τεκμηρίωση από το πρόγραμμα περιήγησης ιστού. Το πραγματικό ζωντανό παράδειγμα τεκμηρίωσης JavaDoc είναι η τεκμηρίωση για βιβλιοθήκες Java στην Oracle Corporation, http://download.oracle.com/javase/6/ έγγραφα /Φωτιά/.
Ε # 3) Χρειάζονται ιδιωτικές μέθοδοι JavaDoc;
Απάντηση: Όχι. Τα ιδιωτικά πεδία και οι μέθοδοι προορίζονται μόνο για προγραμματιστές. Δεν υπάρχει λογική στην παροχή τεκμηρίωσης για ιδιωτικές μεθόδους ή πεδία που δεν είναι προσβάσιμα στον τελικό χρήστη. Το Java Doc δεν δημιουργεί επίσης τεκμηρίωση για ιδιωτικές οντότητες.
τι είναι ένα αρχείο xml και πώς μπορώ να το ανοίξω
Q # 4) Τι είναι η εντολή JavaDoc;
Απάντηση: Αυτή η εντολή αναλύει τις δηλώσεις και τα σχόλια εγγράφων σε αρχεία προέλευσης Java και δημιουργεί αντίστοιχες σελίδες τεκμηρίωσης HTML που περιέχουν τεκμηρίωση για δημόσιες και προστατευμένες κατηγορίες, ένθετες τάξεις, κατασκευαστές, μεθόδους, πεδία και διεπαφές.
Ωστόσο, το JavaDoc δεν δημιουργεί τεκμηρίωση για ιδιωτικές οντότητες και ανώνυμες εσωτερικές τάξεις.
συμπέρασμα
Αυτό το σεμινάριο περιέγραψε το εργαλείο JavaDoc συσκευασμένο με JDK που είναι χρήσιμο για τη δημιουργία της τεκμηρίωσης κώδικα για τον πηγαίο κώδικα Java σε μορφή HTML. Μπορούμε να δημιουργήσουμε τεκμηρίωση είτε εκτελώντας την εντολή Java Doc μέσω εργαλείου εντολών είτε χρησιμοποιώντας την ενσωματωμένη λειτουργικότητα JavaDoc που είναι διαθέσιμη στα περισσότερα Java IDE.
Είδαμε πώς μπορούμε να χρησιμοποιήσουμε το εργαλείο με το IntelliJIdea Java IDE για τη δημιουργία τεκμηρίωσης. Το σεμινάριο εξήγησε επίσης διάφορες ετικέτες που μπορούν να χρησιμοποιηθούν με σχόλια εγγράφων, έτσι ώστε το εργαλείο να μπορεί να δημιουργήσει φιλική προς το χρήστη τεκμηρίωση που να περιγράφει όλες τις πληροφορίες που σχετίζονται με τον πηγαίο κώδικα.
=> Επισκεφθείτε εδώ για να μάθετε Java από το μηδέν.
Συνιστώμενη ανάγνωση
- Βασικά Java: Java Syntax, Java Class και Core Java Concepts
- Ανάπτυξη Java: Δημιουργία και εκτέλεση αρχείου Java JAR
- Java Virtual Machine: Πώς βοηθά το JVM στην εκτέλεση της εφαρμογής Java
- Εκπαιδευτικό πρόγραμμα JAVA για αρχάριους: 100+ πρακτικά εκπαιδευτικά βίντεο Java
- Java Integer και Java BigInteger Class με παραδείγματα
- Java Components: Java Platform, JDK, JRE και Java Virtual Machine
- Πώς να δημιουργήσετε τεκμηρίωση API στον Ταχυδρόμο;