Tôi muốn làm cho một trong những phương thức của mình "không dùng nữa" = không được sử dụng nữa.

Nhưng tôi vẫn muốn có nó trong API của mình. Tôi chỉ muốn hiển thị "cảnh báo" cho bất cứ ai sử dụng phương pháp đó.

Làm thế nào tôi có thể đạt được điều đó?

Sử dụng @Deprecatedtrên phương pháp. Đừng quên làm rõ trường javadoc:

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}

Sử dụng cả @Deprecatedchú thích và@deprecated thẻ JavaDoc.

Các @deprecated thẻ javadoc được sử dụng cho các mục đích tài liệu.

Các @Deprecatedchú thích chỉ thị các trình biên dịch rằng phương pháp này bị phản đối. Dưới đây là những gì nó nói trong tài liệu của Sun / Oracles về chủ đề này:

Sử dụng @Deprecatedchú thích để loại bỏ một lớp, phương thức hoặc trường đảm bảo rằng tất cả các trình biên dịch sẽ đưa ra các cảnh báo khi mã sử dụng phần tử chương trình đó. Ngược lại, không có gì đảm bảo rằng tất cả các trình biên dịch sẽ luôn đưa ra các cảnh báo dựa trên @deprecatedthẻ Javadoc, mặc dù các trình biên dịch Sun hiện đang làm như vậy. Trình biên dịch khác có thể không đưa ra cảnh báo như vậy. Do đó, việc sử dụng @Deprecatedchú thích để tạo cảnh báo sẽ dễ mang theo hơn dựa vào @deprecatedthẻ Javadoc.

Bạn có thể tìm thấy tài liệu đầy đủ tại Cách thức và thời điểm khấu hao API

vì một số giải thích nhỏ đã bị mất

Sử dụng @Deprecatedchú thích trên phương thức như thế này

 /**
 * @param basePrice
 * 
 * @deprecated  reason this method is deprecated <br/>
 *              {will be removed in next version} <br/>
 *              use {@link #setPurchasePrice()} instead like this: 
 * 
 * 
 * <blockquote><pre>
 * getProduct().setPurchasePrice(200) 
 * </pre></blockquote>
 * 
 */
@Deprecated
public void setBaseprice(int basePrice) {
}

nhớ giải thích:

1. Tại sao phương pháp này không còn được khuyến khích . Những vấn đề phát sinh khi sử dụng nó. Cung cấp một liên kết để thảo luận về vấn đề này nếu có. (nhớ tách các dòng để dễ đọc<br/>
2. Khi nào nó sẽ được gỡ bỏ . (cho người dùng của bạn biết họ vẫn có thể dựa vào phương pháp này bao nhiêu nếu họ quyết định theo cách cũ)
3. Cung cấp giải pháp hoặc liên kết đến phương pháp bạn đề xuất {@link #setPurchasePrice()}

Có hai điều bạn có thể làm:

1. Thêm @Deprecated chú thích vào phương thức và
2. Thêm một @deprecatedthẻ vào javadoc của phương thức

Bạn nên làm cả hai !

Trích dẫn tài liệu java về chủ đề này:

Bắt đầu với J2SE 5.0, bạn loại bỏ một lớp, phương thức hoặc trường bằng cách sử dụng chú thích @Deprecated. Ngoài ra, bạn có thể sử dụng thẻ Javadoc @deprecated cho nhà phát triển biết nên sử dụng cái gì để thay thế.

Việc sử dụng chú thích làm cho trình biên dịch Java tạo ra các cảnh báo khi lớp, phương thức hoặc trường không dùng nữa được sử dụng. Trình biên dịch sẽ loại bỏ các cảnh báo không dùng nữa nếu một đơn vị biên dịch không dùng nữa sử dụng một lớp, phương thức hoặc trường không dùng nữa. Điều này cho phép bạn xây dựng các API kế thừa mà không cần tạo cảnh báo.

Bạn nên sử dụng thẻ Javadoc @deprecated với các nhận xét phù hợp giải thích cách sử dụng API mới. Điều này đảm bảo các nhà phát triển sẽ có đường dẫn di chuyển khả thi từ API cũ sang API mới

Sử dụng chú thích @Deprecated cho phương thức của bạn và bạn cũng nên đề cập đến nó trong javadocs.

Hãy nhìn vào @Deprecatedchú thích.