Javadoc @see หรือ {@link}?

184

มีคนบอกความแตกต่างระหว่าง javadoc @seeกับ{@link}ฉันได้ไหม

หรือเมื่อไรที่ควรใช้อันไหน?

java javadoc

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

213

แนวทางอย่างเป็นทางการเกี่ยวกับเรื่องนี้มีความสวยใส

ความแตกต่างการทำงานคือ:

{@link} เป็นลิงค์อินไลน์และสามารถวางได้ทุกที่ที่คุณต้องการ
@see สร้างส่วนของตัวเอง

ในความคิดของฉัน{@link}จะใช้ดีที่สุดเมื่อคุณใช้คลาสฟิลด์ตัวสร้างหรือชื่อวิธีในคำอธิบายของคุณ ผู้ใช้จะสามารถคลิกไปยัง javadoc ของสิ่งที่คุณเชื่อมโยง

ฉันใช้@seeคำอธิบายประกอบใน 2 กรณี:

บางสิ่งเกี่ยวข้องมาก แต่ไม่ได้กล่าวถึงในคำอธิบาย
ฉันอ้างถึงสิ่งเดียวกันหลายครั้งในคำอธิบายและใช้แทนลิงก์หลายลิงก์ในลักษณะเดียวกัน

ฉันใช้ความคิดเห็นนี้ในการตรวจสอบเอกสารโดยสุ่มเพื่อความหลากหลายของสิ่งต่าง ๆ ในไลบรารีมาตรฐาน

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

3

javadoc ไม่เตือนว่า @link ค่อนข้างเข้มข้นและควรใช้เมื่อจำเป็นเท่านั้น

— โทมัส

4

สำหรับคนที่ต้องการคุณจะได้รับรายละเอียดเกี่ยวกับเรื่องนี้ (รวมถึงคำเตือนเกี่ยวกับ@linkในความคิดเห็นข้างต้น) ในคู่มือ Javadoc ของออราเคิล

— Ash Ryan Arnwine

48

@seeสร้างบรรทัดแยกใน Javadocs {@link}สำหรับฝังภายในข้อความ

ฉันใช้@seeเมื่อเป็นนิติบุคคลที่เกี่ยวข้อง แต่ฉันไม่ได้อ้างถึงในข้อความชี้แจง ฉันใช้ลิงก์ภายในข้อความเมื่อมีการเชื่อมต่ออย่างแน่นหนาหรือ (ฉันรู้สึกว่า) ผู้อ่านจะได้รับประโยชน์จากคำแนะนำการนำทางเช่นคุณจะต้องอ้างอิงโดยตรง

— เดฟนิวตัน
แหล่งที่มา

3

มีอีกเอกสารอ้างอิง (ส่วนที่คัดค้าน) เอกสารทางการฉบับเดียวกันที่ต้องการ{@link}มากกว่า@see(ตั้งแต่ Java 1.2):

สำหรับ Javadoc 1.2 และใหม่กว่ารูปแบบมาตรฐานคือการใช้แท็ก @deprecated และแท็ก {@link} ในบรรทัด สิ่งนี้จะสร้างลิงค์ในบรรทัดที่คุณต้องการ ตัวอย่างเช่น:

สำหรับ Javadoc 1.1 รูปแบบมาตรฐานคือการสร้างแท็ก @deprecated และ @see คู่ ตัวอย่างเช่น:

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