Javadoc注释与块注释的比较?
- 论坛
- Javadoc注释与块注释的比较?
21 浏览
Javadoc注释与块注释的比较?
什么时候适合在方法开头使用块注释,什么时候适合使用Javadoc风格的注释?
根据《Java风格指南》中的“注释”部分,我找到了以下内容:
Java程序可以有两种类型的注释:实现注释和文档注释。实现注释与C++中的注释相似,使用/*...*/
或//标记。文档注释(也称为"doc注释")仅适用于Java,使用/**...*/
标记。文档注释可以使用javadoc工具提取为HTML文件。
实现注释用于注释代码或描述特定实现的注释。文档注释用于从无实现的角度描述代码的规范,供不一定具有源代码的开发人员阅读。
因此,换个方式来表达我的问题:什么时候方法需要从无实现的角度(Javadoc)进行代码规范描述,而不是关于特定实现的注释,反之亦然?接口是否需要Javadoc注释,而实现则需要块注释?
编辑:根据迄今为止的答案,我认为我没有正确表达我的问题。
以下是我想要知道的一个示例:
/**
* 这里的Javadoc注释是关于一般实现的?
*/
/*
* 现在,我是否需要一个单独的块注释来描述我的具体实现?
*/
public void foo()
{
...
}
这两种不同的注释风格传达了两种不同类型的信息。是否有情况下,方法应该同时有一个前导的Javadoc注释和一个前导的块注释?
我提问的灵感来自于Eclipse刚刚为我自动生成的这个注释:
/*
* (non-Javadoc)
* @see my.package#process()
*/
我想这里可能有一些未在我上面提供的注释规范中明确声明的样式。