Di mana meletakkan blok komentar doxygen untuk perpustakaan internal - dalam file H atau CPP? [Tutup]


98

Akal sehat mengatakan bahwa blok komentar Doxygen harus diletakkan di file header tempat kelas, struct, enum, fungsi, deklarasi berada. Saya setuju bahwa ini adalah argumen yang kuat untuk perpustakaan yang dimaksudkan untuk didistribusikan tanpa sumbernya (hanya header dan libs dengan kode objek).

TAPI ... Saya telah memikirkan pendekatan yang berlawanan ketika saya mengembangkan pustaka internal perusahaan (atau sebagai proyek sampingan untuk saya sendiri) yang akan digunakan dengan kode sumber lengkapnya. Apa yang saya usulkan adalah untuk meletakkan blok komentar besar di file implementasi (HPP, INL, CPP, dll) agar TIDAK mengacaukan antarmuka kelas dan fungsi yang dideklarasikan di header.

Kelebihan:

  • Lebih sedikit kekacauan di file header, hanya pengelompokan fungsi yang dapat ditambahkan.
  • Blok komentar yang dipratinjau ketika Intellisense misalnya digunakan tidak bentrok - ini adalah cacat yang saya amati ketika saya memiliki blok komentar untuk fungsi di file .H dan memiliki definisi inline di file .H yang sama tetapi disertakan dari file .INL.

Kekurangan:

  • (Yang jelas) Blok komentar tidak ada di file header tempat deklarasinya berada.

Jadi, apa yang Anda pikirkan dan mungkin sarankan?

Jawaban:


77

Letakkan dokumentasi di mana orang akan membaca dan menulisnya saat mereka menggunakan dan mengerjakan kode.

Komentar kelas ditempatkan di depan kelas, komentar metode di depan metode.

Itu adalah cara terbaik untuk memastikan segala sesuatunya terjaga. Itu juga membuat file header Anda relatif ramping dan menghindari masalah menyentuh dari orang yang memperbarui dokumen metode yang menyebabkan header menjadi kotor dan memicu pembangunan kembali. Saya sebenarnya tahu orang-orang menggunakannya sebagai alasan untuk menulis dokumentasi nanti!


11
Saya memiliki pengingat yang menyakitkan tentang mengapa dokumen di header harus dihindari - diberitahu oleh VP senior untuk meletakkan komentar metode di deklarasi kelas dan menemukan diri saya benar-benar menyimpan pengeditan komentar untuk nanti karena menekan header tersebut memicu waktu pembuatan 45 menit !
Andy Dent

7
Bukan downvoting, hanya mempertanyakan: Jika saya mencoba untuk mencari tahu apa yang API (bahkan internal) lakukan, saya lebih suka tidak perlu membuka .cpp dan mengarungi semua kode untuk menemukan dokumentasi. Saya akui akan merepotkan jika Anda mendokumentasikan lebih dari sekadar pandangan klien tentang apa yang dilakukan metode tersebut (seperti bagaimana cara melakukannya), tetapi Anda tidak boleh melakukan itu, bukan?
TED

8
Inti dari menggunakan Doxygen untuk menghasilkan dokumentasi Anda adalah agar dokumentasi yang dihasilkan dapat diakses. Kami memiliki server web internal tempat keluaran Doxygen digunakan dan kami kemudian dapat menggunakan tautan ke halaman di server itu dalam diskusi. Itu juga menghubungkan dokumentasi kelas atau metode dengan halaman tambahan yang membahas masalah desain yang lebih luas.
Andy Dent

1
Memutuskan bagaimana seharusnya diskusi implementasi kepada publik merupakan masalah yang menarik. Tentunya jika ada algoritma atau efek samping tertentu, saya lebih suka mengetahuinya sebagai klien perpustakaan. Terkadang hanya pengelola yang tahu dan Doxygen memiliki cara mudah untuk menandai bagian bersyarat, jadi Anda mungkin membuat dokumen berbeda untuk sudut pandang berbeda.
Andy Dent

77

Saya suka memanfaatkan fakta bahwa nama dapat didokumentasikan di banyak tempat.

Di file header, saya menulis deskripsi singkat tentang metode tersebut, dan mendokumentasikan semua parameternya - ini cenderung tidak berubah daripada penerapan metode itu sendiri, dan jika ya, maka prototipe fungsi perlu diubah dalam hal apa pun .

Saya meletakkan dokumentasi format panjang di file sumber di samping implementasi aktual, sehingga detailnya dapat diubah seiring berkembangnya metode.

Sebagai contoh:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

3
Saya suka metode ini, tetapi tampaknya tidak kompatibel dengan AUTOBRIEF. Saya akan tertarik untuk mengetahui apakah ada solusi konfigurasi untuk menghilangkan beberapa brief yang dihasilkan.
Aaron Wright

Saya juga menyukai metode ini, karena memberikan keseimbangan yang baik dalam implementasi.
Xofo

Saya tidak dapat mereproduksi metode ini di mesin saya, menggunakan Doxygen 1.8.15. Dokumentasi parameter tidak muncul, hanya deskripsi singkat dan rinci.
punyidea

1
Tambahan: Mengubah penempatan deskripsi mendetail ke dalam blok fungsi membuat ini berfungsi untuk saya. Deskripsi sekarang ditambahkan ke akhir deskripsi di dokumen header.
punyidea

19

Memiliki komentar di header berarti bahwa semua pengguna kelas harus dikompilasi ulang jika ada komentar yang diubah. Untuk proyek besar, pembuat kode akan cenderung tidak memperbarui komentar di tajuk jika mereka mengambil risiko menghabiskan 20 menit berikutnya untuk membangun kembali semuanya.

Dan .. karena Anda seharusnya membaca dokumen html dan tidak menelusuri kode untuk dokumentasi, bukan masalah besar bahwa blok komentar lebih sulit ditemukan di file sumber.


Benar, tetapi ini adalah masalah besar jika ini adalah pustaka dinamis yang diambil dari artifactory dan Anda tidak memiliki file sumbernya :-)
DrumM

13

Header: Lebih mudah membaca komentar karena lebih sedikit "gangguan" lainnya saat melihat file.

Sumber: Kemudian Anda memiliki fungsi aktual yang tersedia untuk membaca sambil melihat komentar.

Kami hanya menggunakan semua fungsi global yang dikomentari di header dan fungsi lokal yang dikomentari di sumber. Jika mau, Anda juga dapat menyertakan perintah copydoc untuk memasukkan dokumentasi di banyak tempat tanpa harus menulisnya beberapa kali (lebih baik untuk pemeliharaan)

Namun Anda juga bisa mendapatkan hasil disalin ke dokumentasi file yang berbeda dengan perintah sederhana. Misalnya: -

File saya1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

File SAYA1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Sekarang Anda mendapatkan dokumentasi yang sama pada kedua fungsi tersebut.

Ini memberi Anda lebih sedikit gangguan dalam file kode pada saat yang sama Anda mendapatkan dokumentasi yang ditulis di satu tempat yang disajikan di beberapa tempat di keluaran akhir.


2
kapan blok disalin?
Mert Can Ergün

2

Biasanya saya meletakkan dokumentasi untuk interface (\ param, \ return) di file .h dan dokumentasi untuk implementasi (\ details) di file .c / .cpp / .m. Doxygen mengelompokkan semuanya dalam dokumentasi fungsi / metode.


2

Saya meletakkan semuanya di file header.

Saya mendokumentasikan semuanya, tetapi hanya mengekstrak antarmuka publik secara umum.


2

Saya menggunakan QtCreator untuk pemrograman. Trik yang sangat berguna terdiri dari Ctrl-Clicking pada suatu fungsi atau metode untuk mendapatkan deklarasi di file header.

Ketika metode dikomentari di file header, Anda dapat dengan cepat menemukan informasi yang Anda cari. Jadi bagi saya, komentar harus ditempatkan di file header!


-1

Di c ++ terkadang implementasi dapat dipisahkan antara modul header dan .cpp. Di sini tampaknya lebih bersih untuk memasukkan dokumentasi ke dalam file header karena itu adalah satu-satunya tempat di mana semua fungsi dan metode publik dijamin.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.