如何将Java方法声明或标记为已弃用?
我想使我的一个方法“不推荐”=不再使用。
但我仍然想在我的API中使用它。 我只是想向使用该方法的任何人显示“警告”。
我怎样才能做到这一点?
在方法上使用@Deprecated。 不要忘记澄清javadoc领域:
/** * Does some thing in old style. * * @deprecated use {@link #new()} instead. */ @Deprecated public void old() { // ... }
使用@Deprecated
注释和@deprecated
JavaDoc标签。
@deprecated
JavaDoc标记用于文档的目的。
@Deprecated
注释指示编译器该方法已被弃用。 Sun / Oracles关于这个主题的文档中提到:
使用
@Deprecated
注释来弃用类,方法或字段可确保所有编译器在代码使用该程序元素时都会发出警告。 相反,不能保证所有的编译器总是发出基于@deprecated
Javadoc标签的警告,尽pipe目前Sun编译器是这样做的。 其他编译器可能不会发出这样的警告。 因此,使用@Deprecated
注释来生成警告更便携,依靠@deprecated
Javadoc标签。
您可以在如何和何时弃用API中find完整的文档
有两件事你可以做:
- 将
@Deprecated
注释添加到方法中 - 将
@deprecated
标记添加到方法的javadoc
你应该两个都做 !
引用关于这个主题的java文档 :
从J2SE 5.0开始,通过使用@Deprecated注释来弃用类,方法或字段。 另外,你可以使用@deprecated Javadoc标签告诉开发者使用什么。
使用注释会导致Java编译器在使用不推荐使用的类,方法或字段时生成警告。 如果不build议使用的编译单元使用不推荐使用的类,方法或字段,则编译器会抑制弃用警告。 这使您可以构build传统的API而不会产生警告。
强烈build议您使用Javadoc @deprecated标签,并附上适当的注释,说明如何使用新的API。 这可确保开发人员从旧API到新API具有可行的迁移path
因为一些小的解释失踪
在像这样的方法上使用@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) { }
记得解释一下:
- 为什么这个方法不再被推荐,为了便于阅读,请记住分隔线
- 当它将被删除(让用户知道他们仍然可以依靠这种方法,如果他们仍然坚持旧的方式)
- 为您推荐的方法提供解决scheme或链接
{@link #setPurchasePrice()}
为你的方法使用注解 @Deprecated
,你也应该在你的javadoc中提到它。
看看@Deprecated
注释。