我应该在Java中使用JavaDoc弃用还是注释？

Question

目前,有两种方法可以将代码标记为java中的depreacted.

通过JavaDoc

/**
 * @deprecated
 */

或者作为注释:

@Deprecated

这是我的问题 - 当使用Eclipse将方法标记为已弃用时,我发现声明两者都有点太多了.我真的只想用其中一个.

但是,使用注释会给编译器提供实际有用的附加信息吗？

但是只使用注释,我无法说明为什么该方法被弃用 - 我只能用JavaDoc做到这一点,并且弃用方法而不指出为什么不好.

那么,我可以只使用其中一个吗？或者我应该真的学会指定两者？

Answer 1

你应该同时使用两者.Annotation允许编译器在使用不推荐使用的方法时显示警告,并且javadoc解释了原因.两者都很重要.

根据Oracle的Java Annotations 教程:

不推荐使用元素时,还应使用Javadoc @deprecated标记对其进行记录...

Answer 2

从马的嘴里:

注意:Java语言规范要求编译器在使用标记有@Deprecated注释的类,方法或字段时发出警告.虽然Sun编译器目前这样做,但是当访问标记有@deprecated Javadoc标记的类,方法或字段时,Java语言规范不要求编译器发出警告.

所以基本上,如果你想保证会有编译器警告,你需要使用注释.而且由于某些API设计师令人窒息的无能,您还需要指定javadoc标签以进行解释.

就个人而言,我会说注释是无用的,在修复之前应该省略,因为任何好的编译器或IDE都会显示带有javadoc标记的警告.

Answer 3

你应该指定两者.

注释允许编译器了解它并在使用该方法时触发警告.JavaDoc属性允许开发人员在开始使用它之前了解它.

这是两个非常不同的东西!

Answer 4

您应该两者都写。@Deprecated注释用于编译器，而@deprecated JavaDoc标记用于希望现在为什么不建议使用此方法的人员。

一个示例如下所示：

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