Javadoc: package.html หรือ package-info.java

230

เมื่อพยายามที่จะสร้างความคิดเห็น Javadoc ระดับแพคเกจวิธีการที่ต้องการคืออะไร? คุณทำอะไร?

package-info.java

ข้อดี
- บทความที่ใหม่กว่า
จุดด้อย
- การละเมิดคลาส - คลาสมีไว้สำหรับรหัสไม่ใช่เพื่อความคิดเห็นเท่านั้น

package.html

ข้อดี
- ส่วนขยาย HTML หมายถึงไม่ใช่รหัส
- เน้นไวยากรณ์ในตัวแก้ไขข้อความ / ของ IDE
จุดด้อย
- ไม่มี?

สำหรับฉันฉันใช้ Package.html เสมอ แต่ฉันสงสัยว่ามันเป็นตัวเลือกที่ถูกต้องหรือไม่

java javadoc

— TheLQ
แหล่งที่มา

package-info.javaสามารถมีคำอธิบายประกอบ [แพ็คเกจ] - ไม่ใช่เอกสาร API ทั้งหมด

— Tom Hawtin - tackline

ฉันจะไม่เข้าเกณฑ์ package-info.java เป็นการละเมิดคลาส เป็นไฟล์ต้นฉบับของ java (มีนามสกุลไฟล์ ".java") แต่ไม่ใช่ไฟล์คลาสเนื่องจากไม่มีการประกาศคลาส และในความเป็นจริงมันไม่สามารถมีการประกาศคลาสได้เนื่องจาก "package-info" ไม่ใช่ชื่อคลาสที่ถูกกฎหมาย

— Scrubbie

อีกเหตุผลสำหรับการใช้ package-info.java แทน package.html อาจเป็นได้ว่า. java ไม่ได้หมายความถึงรูปแบบผลลัพธ์เฉพาะของเอกสาร ตัวอย่างเช่นคุณอาจต้องการส่งออก javadoc เป็น LaTeX หรือเป็นไฟล์ PDF ขึ้นอยู่กับการใช้งานคอมไพเลอร์ javadoc สิ่งนี้อาจทำให้เกิดปัญหาในกรณี. html

— honeyp0t

ที่จริง @Scrubbie - แม้ว่าคุณควรจะถูกต้องฉันคิดว่าคุณสามารถระบุชั้นเรียนแพคเกจส่วนตัวในนั้น :-( ฉันเห็นด้วยกับความรู้สึกของคุณแม้ว่าการใช้package-info.javaJavadoc และคำอธิบายประกอบนั้นไม่เป็นการละเมิดคลาส

— mjaggard

@JonasN เห็นstackoverflow.com/a/14708381/751579 (ฉันรู้ว่าคุณมีปัญหานี้ 3 ปีที่ผ่านมา แต่บางทีคนอื่นต้องการคำแนะนำในขณะนี้)

— davidbak

269

package-info.java: "ไฟล์นี้เป็นไฟล์ใหม่ใน JDK 5.0 และเป็นที่ต้องการมากกว่า package.html" - javadoc - ตัวสร้างเอกสาร API ของ Java

ภาคผนวก: ความแตกต่างใหญ่น่าจะเป็นคำอธิบายประกอบแพคเกจ มีน้อยมากในทางของเหตุผลในการเป็น7.4 แพคเกจการประกาศ

ภาคผนวก: คุณลักษณะคำอธิบายประกอบจะกล่าวถึงที่นี่และที่นี่ด้วย

ภาคผนวก: ดูเพิ่มเติมว่ามีอะไรpackage-info.javaบ้าง .

— trashgod
แหล่งที่มา

มีเหตุผลพิเศษว่าทำไมถึงเป็นที่ต้องการ?

— TheLQ

@TheLQ: ฉันคาดเดาบันทึกย่อของแพ็คเกจเนื่องจากคอมไพเลอร์มีข้อมูลเพิ่มเติมที่จะทำงานกับ; เพิ่มเติมข้างต้น

— trashgod

หมายเหตุประกอบแพ็คเกจเป็นสิ่งใหม่สำหรับฉันและดูเหมือนจะเป็นเหตุผลที่ดีสำหรับ package-info.java เนื่องจากขอบเขต

— รถ stacker

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

— Roboprog

ใช้ package-info.java คุณสามารถใช้ {@link} และ doclets อื่น ๆ เมื่อคุณเชื่อมโยงคลาส java.lang เมื่อมีการสร้าง javadoc คุณจะได้รับ {@link} ชี้ไปที่ javadoc ออนไลน์ของคลาสที่ตรงกับ jdk ที่คุณใช้อยู่ IDE ยังสามารถช่วยค้นหาจุดเชื่อมโยงที่ไม่ถูกต้องเมื่อคุณทำการปรับโครงสร้างใหม่อีกครั้ง

— Luigi R. Viggiano