我應該使用 JavaDoc 棄用還是 Java 中的注釋？

Question

目前，有兩種方法可以將 Java 中的代碼標記為已棄用。

通過 JavaDoc

/**
 * @deprecated
 */

或者作為注釋：

@Deprecated

這是我的問題 - 我發現在使用 Eclipse 時將方法標記為已棄用時，聲明兩者有點太多了。 我真的只想使用其中之一。

但是，使用注釋是否會給編譯器提供實際有用的附加信息？

但是僅使用注釋，我無法說明為什么不推薦使用該方法 - 我只能使用 JavaDoc 來做到這一點，並且不推薦使用方法而不說明為什么不好。

那么，我可以只使用其中之一嗎？ 還是我真的應該學會指定兩者？

Answer 1

你應該同時使用兩者。 Annotation 允許編譯器在使用不推薦使用的方法時顯示警告，javadoc 解釋了原因。 兩者都很重要。

根據 Oracle 的 Java 注釋教程：

當一個元素被棄用時，它也應該使用 Javadoc @deprecated 標簽來記錄......

Answer 2

從馬嘴里說：

注意：Java 語言規范要求編譯器在使用標有 @Deprecated 注釋的類、方法或字段時發出警告。 Java 語言規范不要求編譯器在訪問標有 @deprecated Javadoc 標記的類、方法或字段時發出警告，盡管 Sun 編譯器目前會這樣做。

所以基本上，如果你想保證會有編譯器警告，你需要使用注釋。 而且由於某些API設計者的驚人無能，您還需要指定javadoc標簽進行解釋。

就我個人而言，我會說注釋是無用的，在修復之前應該省略，因為任何好的編譯器或 IDE 也會顯示帶有 javadoc 標記的警告。

Answer 3

你應該寫兩個。 @Deprecated 注釋適用於編譯器，@deprecated JavaDoc 標記適用於想知道為什么不推薦使用的人。

一個示例可能如下所示：

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}

Answer 4

您應該同時指定兩者。

注釋讓編譯器知道它並在使用該方法時觸發警告。 JavaDoc 屬性讓開發人員在開始使用它之前就知道。

這是兩種截然不同的東西！

Answer 5

這可以通過一個好的 IDE 輕松處理。

Eclipse Neon，例如。 當我在方法或字段上創建 javadoc @deprecated 時，會自動添加 @Deprecated 注釋。

所以我只是用適當的解釋編寫 javadoc，讓 IDE 在我保存文件的那一刻負責添加 @Deprecated 注釋。