C ++: Membuat Dokumentasi dengan Doxygen - dummies

Kebanyakan programmer benci untuk membuat dokumentasi bahkan lebih dari yang mereka benci untuk mengomentari kode mereka sendiri. Masukkan Doxygen, yang memungkinkan pemrogram menyematkan tag di komentar yang nantinya dapat diekstrak untuk membuat dokumentasi.

Instalasi Doxygen

Doxygen tidak disertai Kode:: Blokir (setidaknya tidak seperti tulisan ini). Anda harus mendownload versi Doxygen yang tepat untuk aplikasi Anda. (Ada juga tautan ke situs web Doxygen dari Kode:: Blok situs.) Setelah Anda menautkan ke situs web Doxygenorg, Anda dapat menavigasi ke halaman download dan menemukan versi Doxygen untuk sistem operasi Anda, seperti yang ditunjukkan di sini:

Download dan pasang versi yang sesuai untuk sistem operasi Anda. Anda bisa menerima defaultnya, tapi ingat di mana wizard penginstalan menempatkan file eksekusi Doxygen.

Sekarang mulai Code:: Blocks. Pilih DoxyBlocks → Open Preferences. Dari sana pilih tab General dan set Path to Doxygen. (Ini adalah jalur yang Anda catat di paragraf sebelumnya.) Jalur default untuk Windows adalah C: Program Filesdoxygenbindoxygen. exe Lakukan hal yang sama untuk Path to Doxywizard. Di sini default untuk Windows adalah C: Program Filesdoxygenbindoxywizard. exe . Anda dapat membiarkan alat lainnya kosong karena tidak diperlukan saat membuat dokumentasi dalam format HTML.

Menambahkan Komentar Dokumentasi

Doxygen menggunakan komentar khusus untuk menandai kata kunci yang membantu alat membuat dokumentasi. Yang membingungkan cukup, Doxygen menerima beberapa standar yang berbeda, namun defaultnya adalah yang paling mirip JavaDoc, komentar / ** , yang tidak masalah. (Anda dapat mengubah gaya komentar ke salah satu dari yang lain dengan memilih DoxyBlocks → Open Preferences dan kemudian memilih tab Comment Style.)

Untuk melihat bagaimana ini bekerja, letakkan kursor di awal sebuah fungsi dan pilih DoxyBlocks → Block Comment (atau tekan Ctrl + Alt + B). Komentar seperti berikut ini muncul (contoh berikut menggunakan program Budget5 yang muncul dalam materi yang dapat didownload di www. Dummies. Com / extras / cplusplus):

/ ** daftar paramlist lengkap & * return void * * / void getAccounts (daftar & accList) {

Kode:: Blok memasukkan komentar blok Doxygen yang dimulai dengan / **. Doxygen tahu bahwa komentar ini termasuk definisi fungsi yang segera diikuti. Kata kunci doxygen dimulai dengan tanda garis miring (backslash). singkat kata kunci menandai uraian singkat tentang fungsinya. Penjelasan singkat bisa lebih dari satu baris.Ini harus menjadi penjelasan singkat tentang fungsi yang muncul dalam tampilan tabel.

Pemrogram dapat mengikuti ini dengan deskripsi yang lebih menyeluruh yang ditandai dengan kata kunci detail . Uraian rinci ini memberikan deskripsi yang lebih menyeluruh tentang fungsi yang dilakukannya.

Banyak kata kunci Doxygen bersifat opsional. Secara khusus, kata kunci details diasumsikan jika Anda memulai paragraf yang terpisah dari deskripsi singkat hanya dengan garis kosong.

Di luar itu adalah baris terpisah yang ditandai dengan kata kunci param untuk menggambarkan setiap argumen ke fungsi tersebut. Akhirnya, kata kunci return menggambarkan nilai yang dikembalikan oleh fungsinya.

Saat diisi, komentar Doxygen untuk getAccounts () mungkin muncul sebagai berikut:

/ ** getAccounts singkat - masukan akun dari keyboard * details Fungsi ini membaca masukan dari keyboard. * Untuk setiap S atau C masuk, fungsinya menciptakan objek * Savings atau Checking baru dan menambahkannya ke daftar akun *. Sebuah X menghentikan masuknya. Masukan lainnya diasumsikan sebagai deposit (angka lebih besar dari * 0) atau penarikan (angka kurang dari 0). * * daftar param accistist & daftar akun * objek yang dibuat oleh getAccounts () * return void * / void getAccounts (daftar & accList) {

Anda juga dapat menambahkan komentar Doxygen pada baris yang sama. Hal ini paling sering digunakan saat mengomentari data anggota. Tempatkan kursor di akhir baris dan pilihlah DoxyBlocks → Line Comment atau tekan Ctrl + Alt + L. Sekarang isi keterangan anggota data. Hasilnya nampak seperti pada contoh berikut juga diambil dari Budget5:

double balance; / ** 

Membangkitkan dokumentasi Doxygen
Doxygen dapat menghasilkan dokumentasi dalam beberapa format yang berbeda, meskipun beberapa (seperti HTML yang dikompilasi) memerlukan unduhan lebih lanjut. Format HTML sangat mudah karena tidak lebih dari tampilan browser.
Defaultnya adalah HTML, tapi jika Anda ingin mengubah format pilih DoxyBlocks → Open Preferences, lalu pilih tab Doxyfile Defaults 2. Di jendela ini Anda dapat memilih semua format berbeda yang ingin Anda hasilkan.
Sebelum mengambil dokumentasi pertama kali, Anda mungkin ingin memilih beberapa opsi lainnya. Pilih DoxyBlocks → Open Preferences, lalu pilih tab Default Doxyfile. Pastikan kotak Extract All dicentang. Selanjutnya pilih tab Doxyfile Defaults 2 dan centang kotak centang Class_Diagrams. Sekarang pilih tab General dan centang kotak Run HTML After Compilation. Klik Oke, dan sudah selesai. (Anda tidak perlu melakukan ini lagi karena pilihan disimpan dalam file bernama doxyfile.)
Pilih DoxyBlocks → Extract Documentation untuk membuat dan melihat dokumentasi. Setelah interval yang cukup singkat, Doxygen membuka browser favorit Anda dengan dokumentasi seperti yang ditunjukkan pada gambar berikut.
Doxygen tidak terlalu user friendly ketika sampai pada kesalahan masukan. Kadang-kadang Doxygen berhenti menghasilkan dokumentasi di beberapa titik di sumber Anda tanpa alasan yang jelas.Periksa doxygen. file log yang terdapat dalam direktori yang sama seperti doxyfile untuk setiap kesalahan yang mungkin terjadi selama ekstraksi.
Gambar berikut menunjukkan peramban proyek di jendela kiri yang memungkinkan pengguna menavigasi dalam dokumentasi proyek. Di sebelah kanan, fungsi getAccounts () telah dipilih untuk mendapatkan deskripsi yang lebih rinci. Uraian singkat muncul di baris pertama, diikuti oleh deskripsi mendetail, parameter, dan nilai pengembalian:

Dokumentasi kelas juga menyeluruh seperti yang ditunjukkan pada cuplikan kode berikut.
/ ** class Account * memberi penjelasan singkat tentang rekening bank abstrak. * details Kelas abstrak ini menggabungkan * propertiescommon ke kedua tipe akun: * Checking and Savings. Namun, kehilangan penarikan konsep * (), yang berbeda * antara dua akun * / class {

Dokumentasi untuk Account ditampilkan di sini:

Perhatikan deskripsi yang muncul di bawah kelas Akun . Ini adalah uraian singkatnya. Mengklik Lebih banyak akan membawa Anda ke deskripsi mendetail. Perhatikan pula representasi grafis dari hubungan pewarisan antara Account , kelas induknya, dan kelas anak-anaknya.