Pertanyaan Doxygen - Blok Komentar Tunggal untuk Beberapa Fungsi


Apakah Anda dapat menggunakan blok komentar tunggal untuk mengomentari beberapa fungsi di doxygen? Di bawah ini adalah contoh sederhana yang tidak berhasil. Bisakah saya melakukan sesuatu yang serupa untuk mendapatkan apa yang saya inginkan?

file.cpp

#include file.h

/// @name FunsGroupedInDoxygen
///@{
/**
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
int fun1(int aParam) {return 0;}
int fun2(int aParam) {return 0;}
///@}

file.h

int fun1(int aParam);
int fun2(int aParam);

Output Doxygen:

warning: Member fun2 (int aParam) (fungsi) file file.h tidak didokumentasikan.


5
2018-05-17 19:08


asal


Jawaban:


Melihat pengelompokan dalam Manual Doxygen di sini ada beberapa metode yang bisa Anda gunakan. Yang menurut saya paling cocok dengan situasi ini disebut Kelompok Anggota.

Anda dapat menentukan grup anggota menggunakan salah satu dari dua gaya:

///@{ 
  ...
///@}

atau

/**@{*/ 
  ... 
/**@}*/

Contoh dari ini adalah:

/** @name FunctionGroup
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
///@{
//* fun1 specific description */
int fun1(int aParam) {return 0;}
//* fun2 specific description */
int fun2(int aParam) {return 0;}
///@}

Ini memungkinkan Anda untuk menentukan grup yang dapat Anda berikan deskripsi umum untuk dan masih memungkinkan Anda menjatuhkan komentar khusus untuk setiap fungsi dalam file doigen yang dibuat.

Saya tidak memiliki oksigen yang terpasang di komputer saya dan tidak dapat menguji kode ini secara langsung, namun jika mengikuti contoh dari grup2 dari bagian grup anggota pada dokumentasi, output yang dikompilasi dari contoh itu adalah ditampilkan di sini, yang diharapkan adalah output yang Anda inginkan.

Edit:

Setelah pengujian, yang sebelumnya berhasil untuk saya tetapi hanya ketika saya mengatur mode ekstraksi yang diinginkan ke Semua Entitas (EXTRACT_ALL = YES di doxyfile). Akan lebih baik untuk hanya menggunakan entitas yang benar-benar didokumentasikan sehingga saya menghabiskan beberapa waktu mencoba pendekatan yang berbeda dari dokumentasi yang disebutkan di atas.

file.h:

/**
 * \defgroup FunctionGroup A Group of Functions
 * @brief Documentation for 2 functions
 * @param aParam A Parameter
 * @retval 0 will always be returned
 * @{
 */ 
int fun1(int aParam);
int fun2(int aParam);
 /** @} */

file.cpp:

#include file.h

/** @ingroup FunctionGroup
 * @brief fun1 specific description
 */
 int fun1(int aParam){
    return 0;
 }
/** @ingroup FunctionGroup
 * @brief fun2 specific description
 */
 int fun2(int aParam){
    return 0;
 }

Berikut ini gambar dari output yang saya dapatkan ketika saya menjalankan Doxygen pada kedua file tersebut: output of doxygen files

Saya menggunakan doxywizard pada mesin windows doxyfile saya yang dihasilkan oleh ini di pastebin.


4
2018-05-17 21:13



Saya tidak yakin tentang satu blok komentar, tetapi cara yang ringkas dan mudah untuk melakukan ini adalah dengan menggunakan @copydoc (referensi di sini), misalnya:

/**
 * @brief Brief description
 * @param aParam A parameter
 */
void foo(int aParam) {}

/**
 * @copydoc foo(int)
 */
void bar(int aParam) {}

3
2018-05-17 19:19