Doxygen กับ Javadoc [ปิด]

Doxygen มีคุณสมบัติหลายอย่างที่ JavaDoc ไม่มีให้ เช่น ไดอะแกรมคลาสสำหรับลำดับชั้นและบริบทความร่วมมือ หน้าสรุปเพิ่มเติม การเรียกดูซอร์สโค้ดเสริม (เชื่อมโยงข้ามกับเอกสารประกอบ) การสนับสนุนแท็กเพิ่มเติม เช่น @todo ในหน้าแยก และสามารถสร้างเอาต์พุตในรูปแบบ TeX และ PDF . นอกจากนี้ยังช่วยให้ปรับแต่งภาพได้มากมาย

เนื่องจาก Doxygen รองรับแท็ก JavaDoc มาตรฐาน คุณจึงสามารถรัน Doxygen บนซอร์สโค้ดใดๆ ที่มีความคิดเห็น JavaDoc อยู่ได้ บ่อยครั้งที่การรันบนซอร์สโค้ดโดยไม่มี JavaDoc นั้นสมเหตุสมผล เนื่องจากการเรียกดูไดอะแกรมและการซอร์สโค้ดสามารถช่วยทำความเข้าใจโค้ดได้แม้ว่าจะไม่มีเอกสารประกอบก็ตาม และเนื่องจากเครื่องมือ JavaDoc ละเว้นแท็กที่ไม่รู้จัก คุณจึงสามารถใช้แท็ก Doxygen เพิ่มเติมได้โดยไม่ทำให้การสร้าง JavaDoc เสียหาย

ทั้งหมดนี้ต้องยอมรับว่าไม่ได้ใช้ Doxygen มาเป็นเวลานานแล้ว ทุกวันนี้ฉันมักจะพึ่งพา IDE ของฉันอย่างมากในการแสดงภาพแบบเดียวกัน และโดยปกติฉันจะไม่อ่าน JavaDoc เป็นหน้า HTML แต่นำเข้าไฟล์ต้นฉบับไปยัง IDE ของฉัน เพื่อให้สามารถสร้าง JavaDoc flyouts และฉันสามารถข้ามไปยังคำจำกัดความได้ นั่นมีพลังมากกว่าที่ Doxygen มอบให้เสียอีก หากคุณต้องการมีเอกสารภายนอก IDE และยินดีใช้งานเครื่องมือที่ไม่ใช่ Java Doxygen ก็คุ้มค่าที่จะลองใช้ เนื่องจากไม่จำเป็นต้องเปลี่ยนแปลงโค้ด Java ของคุณ

ฉันจะใช้ Doxygen กับ Java เท่านั้นหากคุณยังใหม่กับ Java และคุณเคยใช้ Doxygen มาก่อน ซึ่งช่วยลดประสบการณ์การเรียนรู้ที่คุณจะพบกับ javadoc หากคุณไม่เคยใช้ Doxygen มาก่อน ฉันจะเลือกใช้ javadoc ต่อไป เนื่องจากมันได้รับการออกแบบมาโดยเฉพาะโดยคำนึงถึง Java เป็นหลัก หากคุณไม่รู้จักภาษาใดภาษาหนึ่ง และคุณทำงานในภาษา C++ (หรือภาษาอื่นๆ ที่รองรับ) ได้พอๆ กับภาษา Java Doxygen เป็นตัวเลือกที่ดี เพราะคุณจะสามารถใช้ได้กับทั้งสองภาษา

เครื่องมือทั้งสองใช้งานง่ายพร้อมชุดฟีเจอร์ที่คล้ายกัน ทั้งสองมีปลั๊กอิน (หรือสร้างไว้ล่วงหน้า) สำหรับ NetBeans และ Eclipse ทำให้การสร้างเอกสารเร็วยิ่งขึ้น สไตล์ความคิดเห็นที่แต่ละคนใช้มีการทับซ้อนกันอยู่มาก แต่รูปแบบความคิดเห็นเหล่านั้นไม่ เหมือนกันทุกประการ ดังนั้นจึงเป็นเรื่องยากที่จะรวมเข้าด้วยกัน (คุณต้องทราบรายละเอียดของ < em>ทั้งสอง โดยไม่รวมถึงคุณลักษณะใดๆ ที่เฉพาะเจาะจงสำหรับอย่างใดอย่างหนึ่ง) ฉันไม่เคยใช้มัน แต่ดูเหมือนว่าจะมีปลั๊กอิน Maven สำหรับ Doxygen

ฉันชอบความจริงที่ว่าด้วย Doxygen คุณสามารถแสดงคลาสไดอะแกรมในหน้าเดียวกับเอกสารประกอบได้ นอกจากนี้ ฉันชอบที่มันเชื่อมโยงคุณไปยังซอร์สโค้ดโดยตรง หากจำเป็น ฉันไม่ทราบว่า javadoc มีคุณสมบัติเหล่านี้หรือไม่

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

ในทางกลับกัน Doxygen อาจเป็นเรื่องที่ยุ่งยากในการตั้งค่าและทำงานอย่างถูกต้อง แต่หากตั้งค่าอย่างถูกต้อง ก็ควรจะสามารถสร้าง PDF, RTF และ DocBooks รวมถึง HTML ได้ HTML ไม่ได้รับการจัดระเบียบเช่นเดียวกับ JavaDocs เนื่องจาก index.html จะแสดงหน้าว่างตามค่าเริ่มต้น นอกจากนี้ คลาสแบบอินไลน์และสมาชิกแบบคงที่อาจจำเป็นต้องมีแฟล็กพิเศษเพื่อรวมไว้ในเอกสารประกอบ และหากคุณต้องการสร้าง PDF คุณอาจต้องจัดการกับความยุ่งยากในการแจกจ่าย Linux ของคุณโดยไม่มีคำสั่ง pdflatex ที่จำเป็น (เช่น Ubuntu/Mint มี ปัญหาเมื่อเร็ว ๆ นี้) ดังนั้นหากคุณ apt-get ติดตั้งและเรียกใช้ คุณอาจได้รับหน้าจอที่เต็มไปด้วยข้อผิดพลาดแม้จะใช้โปรแกรมธรรมดาก็ตาม เมื่อเทียบกับความง่ายในการรับ javadoc โดยอัตโนมัติเมื่อคุณติดตั้ง API การตั้งค่า Doxygen อาจเป็นประสบการณ์ที่น่าสังเวช เมื่อคุณเอาชนะอุปสรรคได้แล้ว ก็ควรจะมีความยืดหยุ่นมากขึ้นในการจัดการกับโปรเจ็กต์ที่เกี่ยวข้องกับมากกว่าแค่ java