Javadoc注释和块注释有什么区别？

Question

什么情况下在方法开头使用块注释，什么情况下使用javadoc风格的注释更合适？

从Java样式指南的“注释”部分中，我找到了以下内容：

Java程序可以有两种类型的注释：实现注释和文档注释。实现注释是C ++中发现的，由/*...*/和//定界。文档注释（称为“doc注释”）仅适用于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()
 */

我发现这里有一些样式，它没有在上面链接的注释规范中特别声明。

- Tony Stark

Answer 1

需要向 类的使用者 传达的信息应该放在 Javadoc 注释中。

需要向 修改类的开发人员 传达的信息应该放在普通注释（块注释或行注释）中。

任何代码块（类、接口、字段、方法、构造函数等）都可能有 同时 Javadoc 注释和普通注释块，这是为了满足内部和外部文档的需求。

个人而言，我倾向于很少写非 Javadoc 注释，因为我更喜欢以自我说明的方式来组织我的代码。

- Joachim Sauer

---

然而，这并不是我的问题的答案。 - Tony Stark

谢谢。有没有不需要Javadoc注释的方法？我可以想象一个情况是实现接口的类，其中接口中的方法已经有了Javadoc注释。在我的实现中不使用Javadoc注释是否合适？还是最好的经验法则是始终提供Javadoc注释和块注释（以提供用户特定信息以及分离程序员信息）？ - Tony Stark

@hatorade：当我实现一个接口时，通常只在类级别上有一个Javadoc注释。这应该解释了这个实现的全部内容。由接口定义的方法通常不需要进一步的文档，接口中的文档应该足够了。只有当一个方法表现得特别（以接口中未记录的方式）时，才应该有额外的Javadoc注释。 - Joachim Sauer

@Thilo：请注意，在hatorades的评论之后，我编辑了我的回答。 - Joachim Sauer

@thilo：因为我理解Javadoc和块注释之间的区别。我的问题更多地是如何同时使用它们（如果有意义的话），而不是需要传达什么类型的信息。换句话说：在何时提供Javadoc注释，何时只提供块注释，或者在何时提供两者都是适当的。 - Tony Stark

好的回答。我认为只有在确定要创建文档时才应该使用Javadoc注释。并不是所有内容都是API或将成为Apache Commons的一部分。话虽如此，与其没有任何评论，我宁愿接受任何类型的评论。 - Hal50000

Answer 2

在我看来，Javadoc注释是你写给使用你代码的人和调用你方法的人的注释。

Javadoc注释更关注于方法参数，以及根据你给方法传入的参数所返回的内容。

块注释是内部注释，是为了维护你的代码的人而写的注释。

块注释对于理解代码的工作原理、为什么能工作以及使用哪些操作来完成实际工作非常重要。

- Vivien Barousse

---

他们不是同一批人吗...？ - Amy B

@Coronatus：不。我每天阅读JDK和Apache Commons Javadoc，但我并不是任何一个项目的维护者。 - Thilo

有时候，这些人是相同的。但有时候，他们并不相同。以一个著名的Java库Hibernate为例。Javadoc注释是为那些在应用程序中使用Hibernate的人编写的。块注释是为开发Hibernate和阅读Hibernate源代码的人编写的。 - Vivien Barousse

Answer 3

在我看来，在方法顶部放置块注释没有任何意义（好吧，永远不要说“从不”，但至少大多数情况下是这样）。接口方法的Javadoc注释指定了合同，类方法的Javadoc注释则说明了实现方式，因此用户可以决定如果有多个类实现单个接口，则使用哪个类。考虑一下List接口；实现ArrayList和LinkedList在不同的用例中是适当的，因此它们各自的文档可能会解释它们的优缺点。

我内联块注释非常具体。我希望将特定于实现的文档直接放在实现位置。当然，您应该尽可能少地使用它们。使用富有表现力的变量和方法名称，它们会自动添加低级别文档。

Eclipse自动生成的块注释供您填写，并通过添加缺失的星号将其变为Javadoc注释。我不知道它们出现在哪些情况下，但其中一种情况是从现有类中提取接口时。然后，类的Javadoc进入接口方法，类方法获得块注释。其背后的原因是通常在实现接口时您并没有太多要添加的内容。再次以List为例。在ArrayList和LinkedList实现中，size()方法不需要更多文档。它们没有什么有价值的东西可以添加。当然，这个例子是假设的，因为实际实现（至少在OpenJDK中）确实有Javadocs，但我认为没有必要这样做，而且它们没有添加任何有价值的东西。更糟糕的是，它们提供的信息比接口文档还要少。

- musiKk