Java luồng JavaDoc

Question

Tôi đã viết một phương thức chỉ nên được gọi trên một chuỗi cụ thể. Có chú thích hoặc chú thích chuẩn nào nên được thêm vào javadoc của phương thức để biểu thị điều này không?

Answer 1

Không biết bất kỳ chú thích chuẩn nào như vậy. Java Concurrency in Practice giải quyết câu hỏi trong phần 4.5: Chính sách đồng bộ hóa tài liệu. Một vài gợi ý hy vọng giúp bạn làm cho tài liệu của mình rõ ràng và hữu ích:

Ít nhất, hãy ghi lại sự đảm bảo an toàn của một lớp. Nó có an toàn không? Nó làm cho callbacks với một khóa được tổ chức? Có bất kỳ khóa cụ thể nào ảnh hưởng đến hành vi của nó không? Đừng ép buộc khách hàng thực hiện các dự đoán nguy hiểm. Nếu bạn không muốn cam kết hỗ trợ khóa phía máy khách, điều đó tốt, nhưng hãy nói như vậy. Nếu bạn muốn khách hàng có thể tạo các hoạt động nguyên tử mới trên lớp của bạn, như chúng tôi đã làm trong Phần 4.4, bạn cần ghi lại những khóa mà họ nên có để làm như vậy một cách an toàn. Nếu bạn sử dụng khóa để bảo vệ trạng thái, hãy ghi lại điều này cho những người duy trì trong tương lai, bởi vì nó rất dễ dàng - chú thích @GuardedBy sẽ thực hiện thủ thuật. Nếu bạn sử dụng các phương tiện tinh tế hơn để duy trì an toàn luồng, hãy ghi lại chúng vì chúng có thể không rõ ràng đối với người bảo trì.

Chúng cũng sử dụng một số chú thích, không phải là tiêu chuẩn, nhưng được đề xuất bởi chúng (xem Phụ lục A). Tuy nhiên, đối với các phương thức, chúng chỉ cung cấp các biến thể của @GuardedBy, không áp dụng cho trường hợp của bạn.

Tôi khuyên bạn chỉ nên ghi rõ yêu cầu trong Javadoc thuần túy.

Answer 2

Theo tôi, cách tốt nhất để xử lý nó là xóa yêu cầu. Thay đổi phương thức thành riêng tư và đổi tên nó một cách nhẹ nhàng bằng cách thêm từ Workload hoặc Internal hoặc thứ gì đó. Sau đó, tạo một phương thức công khai mới có cùng chữ ký. Yêu cầu phương pháp này kiểm tra xem bạn có đang đi đúng hướng hay không. Nếu bạn đang có, bạn chỉ có thể thực hiện phương pháp riêng. Nếu không, hãy lên lịch phương thức riêng để thực hiện đúng chủ đề. Bằng cách này, người dùng API không phải lo lắng về luồng và chỉ có thể gọi phương thức.

Sau đó, không có gì để chỉ định trong javadoc, mặc dù vẫn hữu ích khi bao gồm thông tin này trong phần mô tả phương pháp công khai và riêng tư.

Đây là mô hình tôi sử dụng khi tôi cần một cái gì đó thực hiện trên EDT:

 
/** 
* Executes something on the EDT with the crazy argument specified. If this is 
* called outside of the EDT, it will schedule the work to be done on the EDT 
* as soon as possible. The actual work of this method is found in 
* {@link #executeSomethingInternal(int)}. 
* 
* @argument crazyArgument some crazy argument 
*/ 
public void executeSomething(int crazyArgument) { 
    if (SwingUtilities.isEventDispatchThread()) { 
    this.executeSomethingInternal(crazyArgument); 
    } else { 
    Runnable r = new Runnable() { 
     private int crazyArgument; 

     public Runnable setCrazyArgument(int crazyArgument) { 
     this.crazyArgument = crazyArgument; 
     return this; 
     } 

     @Override 
     public void run() { 
     this.OuterClass.executeSomethingInternal(this.crazyArgument); 
     } 
    }.setCrazyArgument(crazyArgument); 
    SwingUtilities.invokeLater(r); 
    } 
} 

/** 
* This method actually does the work. It is guaranteed by this class to 
* always get called on the EDT. Users of this API should call 
* {@link #executeSomething(int)}. 
*/ 

private void executeSomethingInternal(int crazyArgument) { 
    // do work here 
}