การใช้ @see ใน JavaDoc?

110

ฉันจะใช้@seeเมื่อจัดการกับ JavaDocs เมื่อใด การใช้งานคืออะไร?

ตัวอย่างเช่นถ้าMethodAโทรMethodBแล้วฉันจะต้องใส่@seeในMethodB's Javadoc และการอ้างอิงMethodAเพราะเห็นว่าเป็นสิ่งที่เรียกว่าหรือฉันต้องใส่การอ้างอิงถึงMethodBจากMethodAเพราะมันเรียกมันว่า ฉันได้อ่านเนื้อหาเกี่ยวกับ@seeบนเว็บไซต์ Oracle และดูเหมือนว่าสำหรับฉันจะคลุมเครืออย่างไม่น่าเชื่อมันบอกว่า "ดูด้วย" แต่ไม่ได้หมายความว่าจริงๆ!

java methods javadoc

— เจฟฟ์
แหล่งที่มา

4

ใส่@seeในMethodB's Javadoc และการอ้างอิงMethodAเพราะเห็นว่าเป็นสิ่งที่เรียกว่า -> วิธีการจะเป็นไปได้เคยรู้วิธีการทั้งหมดซึ่งเรียกวิธีใดวิธีหนึ่งของคุณหรือไม่ แม้ว่าจะเป็นไปได้ (พูดว่าใช้วิธีส่วนตัวเพียงครั้งเดียว) การเชื่อมโยงจากผู้โทรถึงผู้โทรฟังดูแปลก ๆ อย่างน้อย ...

— Mr_and_Mrs_D

1

ความหมายโดยทั่วไปในภาษาอังกฤษ: oxforddictionaries.com/us/definition/american_english/see (คำจำกัดความที่ 1.4)

— stackexchanger

119

ใช่มันค่อนข้างคลุมเครือ

คุณควรใช้เมื่อใดก็ตามสำหรับผู้อ่านเอกสารของวิธีการของคุณอาจเป็นประโยชน์ในการดูวิธีการอื่น ๆ หากเอกสารของ methodA ระบุว่า "ทำงานเหมือน methodB แต่ ... " แสดงว่าคุณควรใส่ลิงค์ อีกทางเลือกหนึ่ง@seeคือ{@link ...}แท็กอินไลน์:

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

เมื่อความจริงที่ว่า methodA เรียก methodB เป็นรายละเอียดการใช้งานและไม่มีความสัมพันธ์ที่แท้จริงจากภายนอกคุณไม่จำเป็นต้องมีลิงค์ที่นี่

— Paŭlo Ebermann
แหล่งที่มา

13

@seeยังมีประโยชน์สำหรับการเชื่อมโยงไปยังทางเลือกอื่นของ@Deprecatedวิธีการ

— Mauve Ranger

1

@MauveRanger เนื่องจาก@seeค่อนข้างคลุมเครือสำหรับสิ่งที่เลิกใช้แล้วฉันคิดว่ามันมีประโยชน์มากกว่าที่จะทำอะไรที่ชัดเจนกว่านี้เช่น:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see มีประโยชน์สำหรับข้อมูลเกี่ยวกับวิธีการ / คลาสที่เกี่ยวข้องใน API มันจะสร้างลิงค์ไปยังวิธีการอ้างอิง / รหัสบนเอกสารประกอบ ใช้เมื่อมีโค้ดที่เกี่ยวข้องซึ่งอาจช่วยให้ผู้ใช้เข้าใจวิธีใช้ API

— ร็อบดอว์สัน
แหล่งที่มา

9

ตัวอย่างที่ดีของสถานการณ์ที่@seeสามารถเป็นประโยชน์ได้คือการนำไปใช้หรือการแทนที่เมธอดคลาสอินเทอร์เฟซ / นามธรรม การประกาศจะมีjavadocส่วนที่ให้รายละเอียดเกี่ยวกับวิธีการและวิธีการแทนที่ / ใช้งานสามารถใช้@seeแท็กโดยอ้างถึงฐาน

คำถามที่เกี่ยวข้อง: เขียน javadoc ด้วย @see?

เอกสาร Java SE: @see

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

2

ไม่ใช่ฉัน แต่อาจเป็นเพราะเรามี @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

เอกสาร java สำหรับ @see เป็นสิ่งที่ดีจริงๆ ควรเป็นอันดับแรก

— dok

2

@vaxquis @inheritDocคัดลอกเอกสารจากที่อื่น ฉันคิดว่าการอธิบายรายละเอียดแทนที่จะเพิ่มปุยมีประโยชน์อย่างไร?

— Nielsvh

@Nielsvg คำตอบนี้ระบุว่าthe overridden/implemented method could use a @see tag, referring to the base one.- และนั่นคือสิ่งที่@inheritDocมีไว้สำหรับ IMO จะดีกว่าที่จะรวมคำอธิบายคลาสพื้นฐานแบบคำต่อคำโดยวิธีการ@inheritDoc และเสริมตามความจำเป็นแทนที่จะอ้างถึงโดย@see- ดู (sic!) stackoverflow.com/questions/11121600/… ; นักพัฒนาจำนวนมาก (ผมรวม) ชอบมีทุกรายละเอียดการดำเนินการในสถานที่หนึ่งแทน neverending ห่วงโซ่ของการเชื่อมโยงขึ้นนำขึ้นผ่านลำดับชั้นมรดก

2

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

— มรุติ
แหล่งที่มา