จะใส่บล็อกข้อคิดเห็นของ doxygen สำหรับไลบรารีภายใน - ในไฟล์ H หรือในไฟล์ CPP ได้อย่างไร [ปิด]

สามัญสำนึกบอกว่าบล็อกข้อคิดเห็นของ Doxygen ต้องใส่ไว้ในไฟล์ส่วนหัวที่มีคลาสโครงสร้าง enums ฟังก์ชันการประกาศอยู่ ฉันยอมรับว่านี่เป็นข้อโต้แย้งที่ดีสำหรับไลบรารีที่ตั้งใจจะแจกจ่ายโดยไม่มีซอร์ส (เฉพาะส่วนหัวและไลบรารีที่มีรหัสออบเจ็กต์)

แต่ ... ฉันเคยคิดถึงวิธีที่ตรงกันข้ามเมื่อฉันพัฒนาไลบรารีภายในของ บริษัท (หรือเป็นโครงการด้านข้างสำหรับตัวฉันเอง) ซึ่งจะใช้กับซอร์สโค้ดแบบเต็ม สิ่งที่ฉันเสนอคือใส่บล็อกความคิดเห็นขนาดใหญ่ในไฟล์การใช้งาน (HPP, INL, CPP ฯลฯ ) เพื่อไม่ให้เกะกะอินเทอร์เฟซของคลาสและฟังก์ชันที่ประกาศในส่วนหัว

ข้อดี:

• ความยุ่งเหยิงน้อยลงในไฟล์ส่วนหัวสามารถเพิ่มได้เฉพาะการจัดหมวดหมู่ของฟังก์ชันเท่านั้น
• บล็อกความคิดเห็นที่แสดงตัวอย่างเมื่อใช้ Intellisense ไม่ได้ปะทะกัน - นี่เป็นข้อบกพร่องที่ฉันสังเกตเห็นเมื่อฉันมีบล็อกความคิดเห็นสำหรับฟังก์ชันในไฟล์. H และมีคำจำกัดความแบบอินไลน์ในไฟล์. H เดียวกัน แต่รวมจากไฟล์. INL

จุดด้อย:

• (สิ่งที่ชัดเจน) บล็อกความคิดเห็นไม่ได้อยู่ในไฟล์ส่วนหัวที่มีการประกาศ

คุณคิดว่าอย่างไรและอาจแนะนำ?

ใส่เอกสารที่ผู้คนจะอ่านและเขียนในขณะที่พวกเขากำลังใช้และทำงานกับโค้ด

ความคิดเห็นของชั้นเรียนจะอยู่หน้าชั้นเรียนวิธีการแสดงความคิดเห็นหน้าวิธีการ

นั่นคือวิธีที่ดีที่สุดในการดูแลรักษาสิ่งต่างๆ นอกจากนี้ยังช่วยให้ส่วนหัวของคุณไฟล์ค่อนข้างลีนและหลีกเลี่ยงการสัมผัสปัญหาของคนอัปเดตเอกสารวิธีการที่ก่อให้เกิดส่วนหัวที่จะสกปรกและเรียกการสร้างใหม่ ฉันรู้ว่าคนใช้เป็นข้ออ้างในการเขียนเอกสารในภายหลัง!

ฉันชอบใช้ประโยชน์จากความจริงที่ว่าชื่อสามารถบันทึกได้ในหลาย ๆ ที่

ในไฟล์ส่วนหัวฉันเขียนคำอธิบายสั้น ๆ เกี่ยวกับวิธีการและบันทึกพารามิเตอร์ทั้งหมด - สิ่งเหล่านี้มีโอกาสน้อยที่จะเปลี่ยนแปลงไปกว่าการใช้งานเมธอดนั้นเองและหากเป็นเช่นนั้นต้นแบบของฟังก์ชันจะต้องมีการเปลี่ยนแปลงไม่ว่าในกรณีใด ๆ .

ฉันใส่เอกสารรูปแบบยาวในไฟล์ต้นฉบับถัดจากการใช้งานจริงดังนั้นรายละเอียดจึงสามารถเปลี่ยนแปลงได้เมื่อวิธีการพัฒนาขึ้น

ตัวอย่างเช่น:

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;
}

การมีความคิดเห็นในส่วนหัวหมายความว่าผู้ใช้ทุกคนในชั้นเรียนจะต้องคอมไพล์ใหม่หากความคิดเห็นมีการเปลี่ยนแปลง สำหรับโปรเจ็กต์ขนาดใหญ่ผู้เขียนโค้ดจะไม่ค่อยมีแนวโน้มที่จะอัปเดตความคิดเห็นในส่วนหัวหากพวกเขาเสี่ยงที่จะใช้เวลา 20 นาทีในการสร้างทุกอย่างใหม่

และ .. เนื่องจากคุณควรอ่าน html doc และไม่ได้เรียกดูโค้ดสำหรับเอกสารประกอบจึงไม่ใช่ปัญหาใหญ่ที่บล็อกความคิดเห็นจะหาตำแหน่งในไฟล์ต้นฉบับได้ยากกว่า

ส่วนหัว: อ่านความคิดเห็นได้ง่ายขึ้นเนื่องจากมี "เสียงรบกวน" อื่น ๆ น้อยกว่าเมื่อดูไฟล์

ที่มา: จากนั้นคุณจะมีฟังก์ชั่นที่แท้จริงสำหรับการอ่านในขณะที่ดูความคิดเห็น

เราเพียงแค่ใช้ฟังก์ชันส่วนกลางทั้งหมดที่แสดงความคิดเห็นในส่วนหัวและฟังก์ชันท้องถิ่นที่แสดงความคิดเห็นในแหล่งที่มา หากคุณต้องการคุณสามารถรวมคำสั่ง copydoc เพื่อแทรกเอกสารในหลาย ๆ ที่โดยไม่ต้องเขียนหลาย ๆ ครั้ง (ดีกว่าสำหรับการบำรุงรักษา)

อย่างไรก็ตามคุณสามารถคัดลอกผลลัพธ์ไปยังเอกสารไฟล์อื่นได้ด้วยคำสั่งง่ายๆ เช่น :-

file1.h ของฉัน

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

ไฟล์ของฉัน 1.c

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

ตอนนี้คุณจะได้รับเอกสารเดียวกันกับทั้งสองฟังก์ชัน

สิ่งนี้ช่วยให้คุณมีเสียงรบกวนน้อยลงในไฟล์โค้ดในเวลาเดียวกันคุณจะได้รับเอกสารที่เขียนในที่เดียวซึ่งนำเสนอในหลาย ๆ ที่ในผลลัพธ์สุดท้าย

โดยปกติฉันจะใส่เอกสารสำหรับอินเทอร์เฟซ (\ param, \ return) ในไฟล์. h และเอกสารสำหรับการนำไปใช้งาน (\ details) ในไฟล์. c / .cpp / .m Doxygen จัดกลุ่มทุกอย่างในเอกสารเกี่ยวกับฟังก์ชัน / วิธีการ

ฉันใส่ทุกอย่างในไฟล์ส่วนหัว

ฉันจัดทำเอกสารทุกอย่าง แต่โดยทั่วไปจะแยกเฉพาะอินเทอร์เฟซสาธารณะเท่านั้น

ฉันใช้ QtCreator สำหรับการเขียนโปรแกรม เคล็ดลับที่มีประโยชน์มากประกอบด้วย Ctrl-Clicking บนฟังก์ชันหรือวิธีการเพื่อรับการประกาศในไฟล์ส่วนหัว

เมื่อวิธีการแสดงความคิดเห็นในไฟล์ส่วนหัวคุณสามารถค้นหาข้อมูลที่ต้องการได้อย่างรวดเร็ว ดังนั้นสำหรับฉันความคิดเห็นควรอยู่ในไฟล์ส่วนหัว!

ใน c ++ บางครั้งการใช้งานสามารถแบ่งระหว่างส่วนหัวและโมดูล. cpp ที่นี่ดูเหมือนว่าจะสะอาดกว่าที่จะใส่เอกสารลงในไฟล์ส่วนหัวเนื่องจากเป็นที่เดียวที่รับประกันฟังก์ชันและวิธีการสาธารณะทั้งหมด