如何将Java方法声明或标记为已弃用？

Question

我想让我的一个方法"弃用"=不再使用了.

但我仍然想在我的API中使用它.我只想向使用该方法的任何人显示"警告".

我怎样才能做到这一点？

Answer 1

用于@Deprecated方法.不要忘记澄清javadoc字段:

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

Answer 2

同时使用@Deprecated注释和@deprecatedJavaDoc标记.

该@deprecatedJavadoc标记被用于文档目的.

所述@Deprecated注释指示,该方法已被弃用的编译器.以下是Sun/Oracles关于该主题的文件:

使用@Deprecated批注来弃用类,方法或字段可确保所有编译器在代码使用该程序元素时发出警告.相反,不能保证所有编译器总是会发出基于@deprecatedJavadoc标记的警告,尽管Sun编译器目前这样做.其他编译器可能不会发出此类警告.因此,使用@Deprecated注释生成警告更依赖于@deprecatedJavadoc标记.

您可以在如何以及何时弃用API中找到完整的文档

Answer 3

因为缺少一些小的解释

@Deprecated在这样的方法上使用注释

 /**
 * @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) {
}

记得解释一下:

1. 为什么不再推荐这种方法.使用它时会出现什么问题.提供有关此事的讨论的链接(如果有的话).(请记住将行分开以便于阅读<br/>
2. 什么时候会被删除.(让您的用户知道,如果他们决定坚持旧方式,他们仍然可以依赖这种方法)
3. 提供您推荐的方法的解决方案或链接 {@link #setPurchasePrice()}

Answer 4

你可以做两件事:

1. 将@Deprecated注释添加到方法中,然后
2. 将@deprecated标记添加到方法的javadoc

你应该两个都做!

引用关于这个主题的java文档:

从J2SE 5.0开始,您可以使用@Deprecated批注来弃用类,方法或字段.此外,您可以使用@deprecated Javadoc标记告诉开发人员使用什么.

使用注释会导致Java编译器在使用不推荐使用的类,方法或字段时生成警告.如果不推荐的编译单元使用不推荐使用的类,方法或字段,则编译器会禁止弃用警告.这使您可以构建旧API而不会生成警告.

强烈建议您使用Javadoc @deprecated标记以及解释如何使用新API的相应注释.这可确保开发人员拥有从旧API到新API的可行迁移路径

Answer 5

使用方法的注释 @Deprecated,您还应该在javadoc中提及它.