Javadoc评论与块评论？

Question

何时在方法开头使用块注释,何时使用javadoc样式的注释是否合适？

从Java样式指南的"注释"部分,我发现了这个:

Java程序可以有两种注释:实现注释和文档注释.实现注释是在C++中找到的,由/*...*//和// 分隔.文档注释(称为"文档注释")仅限Java,并由以下内容分隔/**...*/.可以使用javadoc工具将Doc注释提取到HTML文件.

实现注释用于注释代码或有关特定实现的注释.Doc注释旨在从无实现的角度描述代码的规范.由可能不一定拥有源代码的开发人员阅读.

因此,另一种表达我的问题的方法是:方法何时应该从无实现的角度(Javadoc)而不是关于特定实现的注释来获得代码的规范,反之亦然？接口是否会获得javadoc注释,而实现会获得块注释？

编辑:我认为根据迄今为止的答案,我没有正确地传达我的问题.

这是我想知道的一个例子.

/**
 * Javadoc comment here about general implementation?
 */
/*
 * Should I now have a separate block comment for my specific implementation?
 */
public void foo()
{
...
}

两种不同的评论风格传达两种不同类型的信息.是否存在方法应该具有领先的javadoc注释和前导块注释的情况？

甚至要问的灵感就是Eclipse刚刚为我自动生成了这个:

/*
 * (non-Javadoc)
 * @see my.package#process()
 */

我认为这里有某种样式,我没有在上面链接的评论规范中明确声明.

Answer 1

类的用户需要知道的信息应该进入Javadoc注释.

修改类的开发人员需要知道的信息会进入正常注释(块或行).

当需要公开可见和内部文档时,任何代码块(类,接口,字段,方法,构造函数......)都可能同时具有Javadoc注释和普通注释块.

就个人而言,我倾向于编写非常少的非Javadoc注释,因为我更喜欢以自我记录的方式构建我的代码.

Answer 2

在我看来,Javadoc评论是你写给使用你的代码的人的评论,以及谁调用你的方法.

Javadoc注释更侧重于方法的参数,您的方法将返回的内容取决于您为方法提供的参数.

阻止评论是内部评论,您为维护代码的人编写的评论.

块注释对于理解代码如何工作,工作原理以及用于执行实际工作的操作非常重要.