Cách sử dụng @see trong JavaDoc?

110

Khi nào tôi sử dụng @seekhi xử lý JavaDocs? Cách sử dụng của nó là gì?

Ví dụ, nếu MethodAcuộc gọi MethodBsau đó tôi phải đặt @seetrong MethodBjavadoc 's và tài liệu tham khảo MethodAbởi vì đó là những gì được gọi là nó, hay tôi phải đặt một tham chiếu đến MethodBtừ MethodAvì nó đang gọi nó. Tôi đã đọc những thứ về @seetrang web Oracle và nó đối với tôi nó có vẻ vô cùng mơ hồ, nó nói rằng nó có nghĩa là "nhìn thấy cũng" nhưng không thực sự nghĩa là gì!

java methods javadoc

— Jeff
nguồn

4

đặt @seeở MethodB's javadoc và tài liệu tham khảo MethodAbởi vì đó là những gì gọi nó là -> Làm thế nào sẽ là bao giờ có thể biết tất cả các phương pháp mà gọi một trong những phương pháp của bạn? Thậm chí nếu điều này là có thể (nói một phương pháp riêng được sử dụng một lần duy nhất) nối từ callee để âm thanh gọi ít nhất lạ ...

— Mr_and_Mrs_D

1

Nó có nghĩa là những gì nó thường có nghĩa là bằng tiếng Anh: oxforddictionaries.com/us/definition/american_english/see (định nghĩa 1.4)

— stackexchanger

119

Vâng, nó khá mơ hồ.

Bạn nên sử dụng nó bất cứ khi nào vì người đọc tài liệu về phương pháp của bạn, nó có thể hữu ích khi xem xét một số phương pháp khác. Nếu tài liệu về methodA của bạn cho biết "Hoạt động giống như methodB nhưng ...", thì bạn chắc chắn nên đặt một liên kết. Một thay thế cho @seesẽ là {@link ...}thẻ nội dòng :

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

Khi thực tế methodA gọi methodB là một chi tiết triển khai và không có mối quan hệ thực sự nào từ bên ngoài, bạn không cần liên kết ở đây.

— Paŭlo Ebermann
nguồn

13

@seecũng hữu ích để liên kết đến các lựa chọn thay thế cho @Deprecatedcác phương pháp.

— Mauve Ranger

1

@MauveRanger Vì @seekhá mơ hồ, đối với những thứ không dùng nữa, tôi thấy hữu ích hơn khi làm điều gì đó rõ ràng hơn, như:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see hữu ích cho thông tin về các phương thức / lớp liên quan trong API. Nó sẽ tạo ra một liên kết đến phương thức / mã được tham chiếu trên tài liệu. Sử dụng nó khi có mã liên quan có thể giúp người dùng hiểu cách sử dụng API.

— Rob Dawson
nguồn

9

Một ví dụ điển hình về một tình huống @seecó thể hữu ích khi thực hiện hoặc ghi đè một phương thức lớp giao diện / trừu tượng. Khai báo sẽ có javadocphần trình bày chi tiết phương thức và phương thức được ghi đè / được triển khai có thể sử dụng một @seethẻ, tham chiếu đến cơ sở.

Câu hỏi liên quan: Viết javadoc thích hợp với @see?

Tài liệu Java SE: @see

— AtomHeartFather
nguồn

2

không phải tôi, nhưng có thể là do chúng tôi có @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

tài liệu java cho @see thực sự tốt. nên được đầu tiên.

— dok

2

@vaxquis @inheritDocsao chép tài liệu từ một vị trí khác. Tôi tưởng tượng rằng mô tả chi tiết chứ không phải thêm lông tơ có những công dụng của nó?

— Nielsvh

@Nielsvg câu trả lời này đề cập đến điều đó the overridden/implemented method could use a @see tag, referring to the base one.- và đó chính xác @inheritDoclà những gì dành cho; IMO tốt hơn nên bao gồm nguyên văn mô tả lớp cơ sở @inheritDoc và bổ sung nó khi cần thiết, hơn là tham khảo nó bằng @see- xem (sic!) Stackoverflow.com/questions/11121600/… ; nhiều nhà phát triển (bao gồm cả tôi) thích có tất cả các chi tiết triển khai ở một nơi, thay vì chuỗi liên kết tăng dần lên dẫn lên thông qua hệ thống phân cấp kế thừa.

2

Tôi sử dụng @see để chú thích các phương thức của một lớp triển khai giao diện trong đó mô tả của phương thức đã được cung cấp trong javadoc của giao diện. Khi chúng tôi làm điều đó, tôi nhận thấy rằng Eclipse kéo lên tài liệu của giao diện ngay cả khi tôi đang tìm kiếm phương pháp trên tham chiếu triển khai trong quá trình hoàn tất mã

— Maruthi
nguồn