Giao diện JavaDoc nhận xét

Question

Tôi có giao diện A có phương thức x, y và z. Tôi đang bình luận cho lớp theo cách này:

/** 
* 
* A.java 
* Interface class that has the following methods. 
* 
* @author MyName 
* @since mm-dd-yyyy 
*/ 

public interface A { 

    //method description for x 
    void x(); 

    //method description for y 
    void y(); 

    //method description for z 
    void z(); 
} 

Có đúng hay tôi nên thêm những thứ khác vào NHẬN XÉT?

Answer 1

Có bạn nên viết bình luận Javadoc thích hợp cho giao diện của bạn để cụ thể rõ ràng động lực đằng sau giao diện và hợp đồng dành cho cả người gọi và người triển khai.

Hãy xem xét một số các giao diện trong các mã JDK cho ví dụ, như java.util.List

Answer 2

Không, bạn chưa chỉ định bất kỳ nhận xét JavaDoc nào cho các phương pháp. Làm thế nào là một ai đó sử dụng hoặc thực hiện giao diện có nghĩa là để biết những gì các phương pháp có nghĩa là để làm gì? Bạn nên sử dụng giới thiệu javadoc thích hợp:

/** 
* This method fromulgates the wibble-wrangler. It should not be called without 
* first saturating all glashnashers. 
*/ 
void x(); 

Gấu nhớ rằng không giống như hầu hết các javadoc mà là nhằm mục đích gọi, tài liệu giao diện có hai khán giả: người gọi và thực hiện. Bạn cần phải rõ ràng về những gì cả hai bên có thể mong đợi và cách chúng sẽ hoạt động. Vâng, đây là khó có thể làm tốt :(

EDIT: Về các ý kiến ​​cấp cao nhất:.

• Cá nhân tôi muốn thoát khỏi thẻ @author, vì nó hiếm khi hữu ích IMO (Thông thường tìm trong kiểm soát nguồn là thích hợp hơn ...)
• Trừ khi bạn thực sự có một chính sách có ý nghĩa versioning (không chỉ ngày), tôi muốn thoát khỏi thẻ @since.
• không có điểm nào trong rõ nguồn gốc file
• Một mô tả về "Lớp giao diện có các phương pháp sau đây" là vô nghĩa và mâu thuẫn (như một giao diện không phải là một lớp). Bất kỳ ai đọc JavaDoc cũng sẽ có thể xem danh sách các phương thức. Bạn nên cố gắng cung cấp thêm thông tin ở đây.

Cũng giống như tài liệu lớp bình thường, tài liệu giao diện nên nêu rõ mục đích của loại - vai trò của nó trong sơ đồ lớn hơn, có thể là ví dụ về cách nó được sử dụng, v.v. JDK cho JavaDoc thường hợp lý.