C ++: Mencipta Dokumentasi dengan Doxygen - dummies

Kebanyakan pengaturcara tidak suka membuat dokumentasi bahkan lebih daripada mereka yang tidak suka mengulas kod mereka sendiri. Masukkan Doxygen, yang membolehkan pengaturcara menyemai tag dalam komen yang kemudiannya boleh diekstrak untuk membuat dokumentasi.

Memasang Doxygen

Doxygen tidak datang dengan Kod:: Blok (sekurang-kurangnya tidak seperti tulisan ini). Anda perlu memuat turun versi Doxygen untuk permohonan anda. (Terdapat juga pautan ke laman web Doxygen dari Kod:: Situs Blok.) Selepas anda memaut ke laman web Doxygenorg, anda boleh menavigasi ke halaman muat turun dan mencari versi Doxygen untuk sistem pengendalian anda, seperti yang ditunjukkan di sini:

Muat turun dan pasang versi yang sesuai untuk sistem operasi anda. Anda boleh menerima lalai, tetapi ingat di mana wizard pemasangan meletakkan fail boleh laku Doxygen.

Sekarang mula Kod:: Blok. Pilih DoxyBlocks → Keutamaan Terbuka. Dari sana pilih tab Umum dan tetapkan Path to Doxygen. (Ini adalah jalan yang anda perhatikan dalam perenggan sebelumnya.) Laluan lalai untuk Windows ialah C: Program Filesdoxygenbindoxygen. exe. Lakukan yang sama untuk Path to Doxywizard. Di sini lalai untuk Windows ialah C: Program Filesdoxygenbindoxywizard. exe . Anda boleh meninggalkan alat lain yang kosong kerana mereka tidak diperlukan apabila menghasilkan dokumentasi dalam format HTML.

Menambah Komen Dokumentasi

Doxygen menggunakan ulasan khas untuk menandakan kata kunci yang membantu alat membuat dokumentasi. Dengan cukup mengelirukan, Doxygen menerima beberapa piawai yang berbeza, tetapi lalai adalah yang kelihatan seperti JavaDoc, komentar / ** , yang baik-baik saja. (Anda boleh mengubah gaya komen kepada salah seorang yang lain dengan memilih DoxyBlocks → Keutamaan Terbuka dan kemudian memilih tab Gaya Komen.)

Untuk melihat cara kerja ini, letakkan kursor pada permulaan fungsi dan pilih DoxyBlocks → Block Comment (atau tekan Ctrl + Alt + B). Sebutan seperti berikut dipaparkan (contoh berikut menggunakan program Budget5 yang terdapat dalam bahan yang boleh dimuat turun di www. Dummies com / extras / cplusplus):

/ ** brief * * param accList list & * return void * * / tidak sah getAccounts (senarai & accList) {

Code:: Blok memasukkan komentar blok Doxygen bermula dengan / **. Doxygen tahu bahawa ulasan ini tergolong dalam definisi fungsi yang segera berikut. Kata kunci Doxygen bermula dengan (backslash). Bendera singkat kata kunci penerangan ringkas mengenai fungsi tersebut. Keterangan ringkas boleh memanjangkan lebih dari satu baris.Ini harus menjadi penerangan ringkas tentang fungsi yang muncul dalam paparan tabular.

Pengaturcara boleh mengikuti ini dengan penerangan yang lebih lengkap ditandai dengan kata kunci butiran . Penerangan terperinci ini memberikan penerangan yang lebih lengkap tentang fungsi yang dilakukan.

Banyak kata kunci Doigen adalah pilihan. Khususnya, kata kunci butiran diandaikan jika anda memulakan perenggan yang dipisahkan dari deskripsi ringkas dengan tidak lebih dari satu baris kosong.

Di luar itu adalah baris berasingan yang ditandai dengan kata kunci param untuk menggambarkan setiap argumen pada fungsi tersebut. Akhirnya, kata kunci kembali menerangkan nilai yang dikembalikan oleh fungsi tersebut.

Apabila diisi, komen Doxygen untuk getAccounts () mungkin muncul seperti berikut:

/ ** mendapatkan ringkas Akaun - akaun input dari papan kekunci * butiran Fungsi ini membaca input dari papan kekunci. * Untuk setiap S atau C yang dimasukkan, fungsi ini membuat objek akaun Simpanan atau Semakan baru dan menambahkannya ke senarai akaun *. X menamatkan kemasukan. Mana-mana input * lain dianggap sebagai deposit (nombor lebih besar daripada * 0) atau pengeluaran (nombor kurang daripada 0). Senarai * senarai param & senarai akaun * objek yang dicipta oleh getAccounts () * return void * / void getAccounts (list & accList) {

Anda juga boleh menambah komentar Doxygen pada baris yang sama. Ini paling sering digunakan ketika mengulas ahli data. Letakkan kursor di hujung baris dan sama ada pilih DoxyBlocks → Line Comment atau tekan Ctrl + Alt + L. Sekarang isikan perihalan ahli data. Hasilnya muncul seperti contoh berikut yang juga diambil dari Bajet5:

keseimbangan ganda; / ** 

Menjana dokumentasi Doxygen
Doxygen boleh menghasilkan dokumentasi dalam beberapa format yang berbeza, walaupun beberapa (seperti HTML yang dikompil) memerlukan muat turun selanjutnya. Format HTML amat mudah kerana ia memerlukan apa-apa lebih daripada pelayar untuk dilihat.
Lalai adalah HTML, tetapi jika anda ingin menukar format pilih DoxyBlocks → Keutamaan Terbuka, kemudian pilih tab Default Doxyfile 2. Dalam tetingkap ini, anda boleh memilih semua format yang berbeza yang anda ingin hasilkan.
Sebelum mengekstrak dokumentasi buat kali pertama, anda mungkin mahu memilih beberapa pilihan lain. Pilih DoxyBlocks → Keutamaan Terbuka, dan kemudian pilih tab Default Doxyfile. Pastikan kotak Extract All diperiksa. Seterusnya pilih tab Default Doxyfile 2 dan semak kotak semak Class_Diagrams. Sekarang pilih tab Umum dan semak Run HTML After Compilation box. Klik OK, dan anda sudah selesai. (Anda tidak perlu melakukan ini lagi sebagai pilihan yang disimpan dalam fail yang dipanggil doxyfile.)
Pilih DoxyBlocks → Ekstrak Dokumentasi untuk menjana dan melihat dokumentasi. Selepas jarak yang agak singkat, Doxygen membuka penyemak imbas kegemaran anda dengan dokumentasi seperti yang ditunjukkan dalam angka berikut.
Doxygen tidak begitu mesra pengguna apabila datang kepada ralat masukan. Kadang-kadang Doxygen hanya berhenti membuat dokumentasi pada suatu ketika di sumber anda tanpa sebab yang jelas.Semak doxygen itu. fail log yang terkandung dalam direktori yang sama dengan fail doxy untuk sebarang ralat yang mungkin berlaku semasa pengekstrakan.
Imej berikut menunjukkan pelayar projek di tetingkap kiri yang membolehkan pengguna menavigasi dalam dokumentasi projek. Di sebelah kanan, fungsi getAccounts () telah dipilih untuk mendapatkan penerangan yang lebih terperinci. Keterangan ringkas muncul pada baris pertama, diikuti dengan penerangan terperinci, parameter, dan nilai pulangan:

Dokumentasi kelas juga sama seperti yang ditunjukkan oleh coretan kod berikut.
/ ** Akaun kelas * ringkas akaun bank abstrak. * butir-butir Kelas abstrak ini menggabungkan * sifat khas kepada kedua-dua jenis akaun: * Pemeriksaan dan Simpanan. Walau bagaimanapun, ia hilang * konsep pengeluaran (), yang berbeza * antara dua * / Akaun kelas {

Dokumentasi untuk Akaun ditunjukkan di sini:

kelas Akaun . Ini adalah penerangan ringkas. Mengklik Lagi akan membawa anda ke huraian terperinci. Juga perhatikan gambaran grafik hubungan warisan antara Akaun , kelas induknya, dan kelas anak-anaknya.