C ++: Δημιουργία τεκμηρίωσης με Doxygen - dummies

Οι περισσότεροι προγραμματιστές μοιράζονται να δημιουργήσουν τεκμηρίωση ακόμη περισσότερο από ό, τι μισούν να σχολιάσουν τον δικό τους κώδικα. Εισαγάγετε το Doxygen, το οποίο επιτρέπει στους προγραμματιστές να ενσωματώσουν ετικέτες στα σχόλια που μπορούν αργότερα να εξαχθούν για να δημιουργήσουν την τεκμηρίωση.

Εγκατάσταση του Doxygen

Το Doxygen δεν συνοδεύεται από τον κώδικα:: Μπλοκ (τουλάχιστον όχι από αυτή τη γραφή). Θα χρειαστεί να κατεβάσετε τη σωστή έκδοση του Doxygen για την αίτησή σας. (Υπάρχει επίσης ένας σύνδεσμος στον ιστότοπο Doxygen από τον κώδικα:: Blocks site.) Αφού συνδεθείτε στον ιστότοπο Doxygenorg, μπορείτε να μεταβείτε στη σελίδα λήψης και να βρείτε την έκδοση του Doxygen για το λειτουργικό σας σύστημα, όπως φαίνεται εδώ:

Κατεβάστε και εγκαταστήστε την έκδοση που είναι κατάλληλη για το λειτουργικό σας σύστημα. Μπορείτε να αποδεχτείτε τις προεπιλογές, αλλά να θυμάστε πού ο οδηγός εγκατάστασης βάζει το εκτελέσιμο αρχείο Doxygen.

Τώρα ξεκινήστε τον Κωδικό:: Αποκλεισμός. Επιλέξτε DoxyBlocks → Open Preferences. Από εκεί, επιλέξτε την καρτέλα Γενικά και ορίστε τη Διαδρομή στο Doxygen. (Αυτή είναι η διαδρομή που σημειώσατε στην προηγούμενη παράγραφο.) Η προεπιλεγμένη διαδρομή για τα Windows είναι C: Program Filesdoxygenbindoxygen. exe. Κάντε το ίδιο για το Path to DoWizard. Εδώ η προεπιλογή για τα Windows είναι C: Program Filesdoxygenbindoxywizard. exe . Μπορείτε να αφήσετε τα υπόλοιπα εργαλεία κενά, καθώς δεν είναι απαραίτητα όταν δημιουργείτε τεκμηρίωση σε μορφή HTML.

Προσθήκη Σχολίων Τεκμηρίωσης

Το Doxygen χρησιμοποιεί ειδικά σχόλια για να επισημάνει τις λέξεις-κλειδιά που βοηθούν το εργαλείο στη δημιουργία τεκμηρίωσης. Αρκετά σύγχυση, το Doxygen δέχεται αρκετά διαφορετικά πρότυπα, αλλά η προεπιλογή είναι αυτή που μοιάζει περισσότερο με το JavaDoc, το σχόλιο / ** , το οποίο είναι εντάξει. (Μπορείτε να αλλάξετε το στυλ σχολιασμού σε ένα από τα άλλα, επιλέγοντας DoxyBlocks → Άνοιγμα προτιμήσεων και στη συνέχεια επιλέγοντας την καρτέλα Style Style.)

Για να δείτε πώς λειτουργεί αυτό, τοποθετήστε το δρομέα στην αρχή μιας λειτουργίας και επιλέξτε DoxyBlocks → Block Comment (ή πατήστε Ctrl + Alt + B). Ένα σχόλιο όπως το παρακάτω εμφανίζεται (τα παρακάτω παραδείγματα χρησιμοποιούν το πρόγραμμα Budget5 που εμφανίζεται στο υλικό που μπορείτε να κατεβάσετε στο www. Dummies. Com / extras / cplusplus):

/ ** brief * * param accList list & * return void * * / void getAccounts (λίστα & accList) {

Κωδικός:: Τα μπλοκ εισάγουν ένα σχόλιο μπλοκ Doxygen που αρχίζει με / **. Το Doxygen γνωρίζει ότι αυτό το σχόλιο ανήκει στον ορισμό της λειτουργίας που ακολουθεί αμέσως. Οι λέξεις-κλειδιά Doxygen ξεκινούν με μια (ανάστροφη κάθετο). Η σύντομη λέξη-κλειδί σημαδεύει τη σύντομη περιγραφή της λειτουργίας. Η σύντομη περιγραφή μπορεί να εκτείνεται σε περισσότερες από μία γραμμές.Αυτή θα πρέπει να είναι μια σύντομη περιγραφή της λειτουργίας που εμφανίζεται στις πινακοποιημένες οθόνες.

Ο προγραμματιστής μπορεί να ακολουθήσει μια πιο εμπεριστατωμένη περιγραφή με τη λέξη-κλειδί λεπτομέρειες . Αυτή η λεπτομερής περιγραφή παρέχει μια λεπτομερέστερη περιγραφή του τι κάνει η λειτουργία.

Πολλές από τις λέξεις-κλειδιά Doxygen είναι προαιρετικές. Συγκεκριμένα, η λέξη λεπτομέρειες λέξη-κλειδί θεωρείται εάν ξεκινήσετε μια παράγραφο που χωρίζεται από την περιγραφή σύντομη από τίποτα περισσότερο από μια κενή γραμμή.

Πέρα από αυτό υπάρχει μια ξεχωριστή γραμμή που έχει επισημανθεί με τη λέξη param για να περιγράψει κάθε όρο στη λειτουργία. Τέλος, η λέξη-κλειδί επιστροφής περιγράφει την τιμή που επέστρεψε η λειτουργία.

Όταν συμπληρωθεί, το σχόλιο Doxygen για getAccounts () μπορεί να εμφανιστεί ως εξής:

/ ** brief getAccounts - εισάγει λογαριασμούς από το πληκτρολόγιο * λεπτομέρειες Αυτή η λειτουργία διαβάζει την είσοδο από το πληκτρολόγιο. * Για κάθε είσοδο S ή C, η λειτουργία δημιουργεί ένα νέο αντικείμενο * Savings ή Checking account και το προσθέτει στη λίστα λογαριασμών *. Ένα X τερματίζει την καταχώρηση. Οποιαδήποτε άλλη είσοδος * θεωρείται ότι είναι κατάθεση (αριθμοί μεγαλύτερες από * 0) ή ανάληψη (αριθμοί μικρότεροι από 0). * * param accList list & η λίστα των λογαριασμών * αντικείμενα που δημιουργούνται από getAccounts () * return void * / void getAccounts (λίστα & accList) {

Μπορείτε επίσης να προσθέσετε ένα σχόλιο Doxygen στην ίδια γραμμή. Αυτό χρησιμοποιείται συνήθως όταν σχολιάζετε μέλη δεδομένων. Τοποθετήστε το δρομέα στο τέλος της γραμμής και επιλέξτε DoxyBlocks → Line Comment ή πιέστε Ctrl + Alt + L. Τώρα συμπληρώστε μια περιγραφή του μέλους δεδομένων. Το αποτέλεσμα εμφανίζεται όπως και στο ακόλουθο παράδειγμα που λαμβάνεται επίσης από τον προϋπολογισμό5:

διπλό υπόλοιπο. / ** <το υπόλοιπο του τρέχοντος λογαριασμού * /

Δημιουργία τεκμηρίωσης Doxygen

Το Doxygen μπορεί να δημιουργήσει τεκμηρίωση σε πολλές διαφορετικές μορφές, αν και μερικές (όπως compiled HTML) απαιτούν περαιτέρω λήψεις. Η μορφή HTML είναι ιδιαίτερα βολική, καθώς δεν χρειάζεται τίποτα περισσότερο από ένα πρόγραμμα περιήγησης για προβολή.

Η προεπιλογή είναι HTML, αλλά αν θέλετε να αλλάξετε τη μορφή επιλέξτε DoxyBlocks → Open Preferences και, στη συνέχεια, επιλέξτε την καρτέλα Doxyfile Defaults 2. Σε αυτό το παράθυρο μπορείτε να επιλέξετε όλες τις διαφορετικές μορφές που θέλετε να δημιουργήσετε.

Πριν από την εξαγωγή της τεκμηρίωσης την πρώτη φορά, ίσως θέλετε να επιλέξετε μερικές άλλες επιλογές. Επιλέξτε DoxyBlocks → Open Preferences και στη συνέχεια επιλέξτε την καρτέλα Defaults Doxyfile. Βεβαιωθείτε ότι έχει επιλεγεί το πλαίσιο Εξαγωγή όλων. Στη συνέχεια, επιλέξτε την καρτέλα Προεπιλογές Doxyfile 2 και ελέγξτε το πλαίσιο ελέγχου Class_Diagrams. Τώρα επιλέξτε την καρτέλα Γενικά και επιλέξτε το πλαίσιο Εκτέλεση HTML μετά τη συμπλήρωση. Κάντε κλικ στο κουμπί OK και τελειώσατε. (Δεν θα χρειαστεί να το κάνετε ξανά καθώς οι επιλογές αποθηκεύονται σε ένα αρχείο που ονομάζεται doxyfile.)

Επιλέξτε DoxyBlocks → Extract Documentation για να δημιουργήσετε και να δείτε την τεκμηρίωση. Μετά από ένα αρκετά σύντομο χρονικό διάστημα, το Doxygen ανοίγει το αγαπημένο σας πρόγραμμα περιήγησης με τεκμηρίωση όπως αυτή που φαίνεται στο παρακάτω σχήμα.

Το Doxygen δεν είναι πολύ φιλικό προς το χρήστη όταν πρόκειται για σφάλματα εισόδου. Μερικές φορές το Doxygen σταματά να παράγει τεκμηρίωση σε κάποια στιγμή στην πηγή σας χωρίς προφανή λόγο.Ελέγξτε το δοξυγόνο. αρχείο καταγραφής που περιέχεται στον ίδιο κατάλογο με το αρχείο doxy για τυχόν σφάλματα που μπορεί να έχουν συμβεί κατά την εξαγωγή.

Η παρακάτω εικόνα δείχνει το πρόγραμμα περιήγησης έργου στο αριστερό παράθυρο που επιτρέπει στο χρήστη να πλοηγηθεί στην τεκμηρίωση του έργου. Στα δεξιά, η λειτουργία getAccounts () έχει επιλεγεί προκειμένου να αποκτηθεί μια πιο λεπτομερής περιγραφή. Η σύντομη περιγραφή εμφανίζεται στην πρώτη γραμμή, ακολουθούμενη από την λεπτομερή περιγραφή, τις παραμέτρους και την τιμή επιστροφής:

Η τεκμηρίωση κλάσης είναι εξίσου διεξοδική με αυτή που παρουσιάζεται στο ακόλουθο απόσπασμα κώδικα.

/ ** κατηγορία λογαριασμός * σύντομη μια αφηρημένη τραπεζικό λογαριασμό. * λεπτομέρειες Αυτή η αφηρημένη κλάση ενσωματώνει * propertiescommon και στους δύο τύπους λογαριασμού: * Έλεγχος και εξοικονόμηση πόρων. Ωστόσο, λείπει η απόσυρση της έννοιας * (*), η οποία είναι διαφορετική * μεταξύ των δύο * / class Account {

Η τεκμηρίωση για το Λογαριασμό εμφανίζεται εδώ:

Παρατηρήστε την περιγραφή που εμφανίζεται κάτω από class Λογαριασμός . Αυτή είναι η σύντομη περιγραφή. Κάνοντας κλικ στην επιλογή Περισσότερα θα μεταβείτε στη λεπτομερή περιγραφή. Επίσης, παρατηρήστε τη γραφική αναπαράσταση της σχέσης κληρονομιάς μεταξύ Λογαριασμού , των γονικών τάξεων και των τάξεων των παιδιών.