Javadoc注释与块注释的比较?

21 浏览
0 Comments

Javadoc注释与块注释的比较?

什么时候适合在方法开头使用块注释,什么时候适合使用Javadoc风格的注释?

根据《Java风格指南》中的“注释”部分,我找到了以下内容:

Java程序可以有两种类型的注释:实现注释和文档注释。实现注释与C++中的注释相似,使用/*...*/或//标记。文档注释(也称为"doc注释")仅适用于Java,使用/**...*/标记。文档注释可以使用javadoc工具提取为HTML文件。

实现注释用于注释代码或描述特定实现的注释。文档注释用于从无实现的角度描述代码的规范,供不一定具有源代码的开发人员阅读。

因此,换个方式来表达我的问题:什么时候方法需要从无实现的角度(Javadoc)进行代码规范描述,而不是关于特定实现的注释,反之亦然?接口是否需要Javadoc注释,而实现则需要块注释?

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

以下是我想要知道的一个示例:

/**

* 这里的Javadoc注释是关于一般实现的?

*/

/*

* 现在,我是否需要一个单独的块注释来描述我的具体实现?

*/

public void foo()

{

...

}

这两种不同的注释风格传达了两种不同类型的信息。是否有情况下,方法应该同时有一个前导的Javadoc注释和一个前导的块注释?

我提问的灵感来自于Eclipse刚刚为我自动生成的这个注释:

/*

* (non-Javadoc)

* @see my.package#process()

*/

我想这里可能有一些未在我上面提供的注释规范中明确声明的样式。

0