Cách tốt nhất để sử dụng JavaDoc để tạo tài liệu cho Java enum là gì?

Question

Tôi vừa mới bắt đầu sử dụng các enums của Java trong các dự án của riêng mình (tôi phải sử dụng JDK 1.4 tại nơi làm việc) và tôi nhầm lẫn là cách thực hành tốt nhất khi sử dụng JavaDoc cho một enum.

Tôi đã tìm thấy rằng phương pháp này hoạt động, nhưng mã kết quả là một chút unrefined:

/** 
* Doc for enum 
*/ 
public enum Something { 
/** 
* First thing 
*/ 
FIRST_THING, 
/** 
* Second thing 
*/ 
SECOND_THING; 
//could continue with more 
} 

Có cách nào tôi có thể phá vỡ các tờ khai enum trên đường riêng của họ mà không chaining chúng bằng dấu phẩy, hoặc đây có phải là cách tiếp cận tốt nhất để sử dụng JavaDoc cho một enum không?

Answer 1

Để trả lời phần đầu tiên của câu hỏi, bạn phải tách từng giá trị enum bằng dấu phẩy. Theo như tôi biết, không có cách nào xung quanh đó.

Cá nhân tôi không gặp sự cố với mã theo cách bạn đã trình bày. Có vẻ như một cách hoàn toàn hợp lý để tài liệu một enum với tôi.

Answer 2

Có một google mã tìm kiếm trực tuyến công cụ - http://www.google.com/codesearch

tôi cố gắng để tra cứu thứ bằng cách thực hiện một cái gì đó giống như "lang:java public enum"

An example from Sun

Answer 3

Như Mike đã đề cập, bạn phải tách các giá trị enum với dấu phẩy, và chúng phải là những thứ đầu tiên được liệt kê trong khai báo enum (các biến mẫu, các hằng, các hàm tạo và các phương thức có thể làm theo).

Tôi nghĩ cách tốt nhất để ghi tài liệu là tương tự như các lớp thông thường: kiểu enum được mô tả về hàm và vai trò của enum như một tổng thể ("Something values are used to indicate which mode of operation a client wishes...") và mỗi giá trị enum được mô tả Javadoc mục đích và chức năng ("FIRST_THING indicates that the operation should evaluate the first argument first..").

Nếu mô tả giá trị enum ngắn, bạn có thể muốn đặt chúng trên một dòng là /** Evaluate first argument first. */, nhưng tôi khuyên bạn nên giữ từng giá trị enum trên một dòng riêng. Hầu hết các IDE có thể được cấu hình để định dạng chúng theo cách này một cách tự động.