Chú thích để tắt JavaDocs

Question

Có chú thích nào để khai báo rằng một phương thức nhất định sẽ không được đưa vào JavaDocs ngay cả khi nó được công khai?

Cái gì như:

@nojavadocs 
public void foo(){ 
//... 
} 

---

T.B. Tôi hiểu điểm ở đây về API, nhưng các phương thức đơn giản là "không được hỗ trợ". Chúng hoạt động (và phải công khai để truy cập từ các gói khác), nhưng chúng tôi không muốn làm phiền chúng và trả lời các câu hỏi về cách sử dụng chúng khi chức năng của chúng không liên quan đến các kịch bản sử dụng được hỗ trợ. Thiết kế tốt có thể có nghĩa là di chuyển chúng sang một lớp khác, nhưng chúng tham chiếu một cách logic về dữ liệu trong lớp.

Answer 1

Không nếu bạn đang sử dụng công cụ JavaDocs của Sun.

Họ có a feature request cho nó, nhưng nó được ưu tiên thấp từ năm 1997.

Bạn có thể viết một Doclet tùy chỉnh để khắc phục điều này, hoặc sử dụng một công cụ của bên thứ 3 (DocFlex hay như vậy).

Answer 2

Có ... nhưng không theo cách tốt (có phương pháp công khai không thực sự "công khai" không phải là một phương pháp thiết kế tuyệt vời).

Bạn có thể thực hiện theo đề xuất được đưa ra trong this thread và đánh dấu phương pháp bằng cách sử dụng @deprecated khi đó khi bạn chạy tùy chọn sử dụng javadoc -nodeprecated.

Chỉnh sửa: Như những người khác đã lưu ý, đây là không phải là một hành động mong muốn. Điều này sẽ giải quyết vấn đề của bạn, nhưng bạn thực sự cần phải suy nghĩ lại lý do tại sao nó là bạn muốn ẩn phương pháp - cho một phiên bản biên dịch mã của bạn, ai đó sẽ vẫn có thể thấy chức năng của bạn; ẩn nó trong tài liệu không thực tế ẩn phương thức. Tôi thực sự muốn nhấn mạnh ở đây rằng các vòng loại private, public và protected có nghĩa là bạn nên xem xét và sử dụng hiệu quả. Không có phương thức "ẩn" public phương pháp.

Answer 3

Lý do duy nhất tôi có thể nghĩ rằng bạn muốn làm điều này sẽ là "ẩn" phương thức theo một nghĩa nào đó, nếu chỉ về mặt tài liệu. Nếu bạn làm điều đó, bạn sẽ thiết kế tài liệu bị "hỏng" theo nghĩa là tài liệu bị hỏng khi nó hết hạn và không còn phản ánh chính xác những gì lớp học làm. Vì phương thức này vẫn là một phần của API công cộng, bạn không thực sự ẩn nó.

Nếu bạn muốn một phương thức không được sử dụng bên ngoài lớp học hoặc một vài người dùng, hãy đặt nó ở chế độ riêng tư hoặc gói. Nếu điều này là bất tiện và nó phải được công khai, tôi chỉ ghi rõ các hạn chế về việc sử dụng nó, có thể với quy ước đặt tên (ví dụ, python thực hiện điều này, có tên thực thể được bao quanh bởi dấu gạch dưới, mà bạn có thể thấy nhưng có nghĩa là tham gia nhiều hơn vào việc triển khai lớp học so với api công khai)

Answer 4

/** 
* Don't use this method <br> 
* <i>or all your data will be lost.</i> 
*/ 
public void foo(){ 
    //... 
} 

tốt, sử dụng một lời giải thích tốt hơn tại sao người dùng không nên sử dụng phương pháp này ...
Hãy nhớ rằng nó không phải là khó để tìm thấy bất kỳ phương pháp (công cộng) sử dụng một decompiler hoặc Reflection.