为什么Java接口在docs中有描述

Question

我知道接口里面只有方法声明，只有当某些类实现接口时才会提供它们的实现（我不是在谈论默认方法或功能接口）。

问题是：为什么Java文档，资料，书籍或其他信息来源提供了界面的描述＆＃39;方法？例如，http://docs.oracle.com/javase/7/docs/api/index.html?java/util/List.html提供了List接口方法的完整描述，但如果它只是一个接口，那么这些方法不应该提供任何功能，那么这些文档中描述了什么呢？

Answer 1

描述是接口对象及其方法的目标，如果没有描述，当您实现此接口对象时，您将不知道如何在方法中编写。

例如，方法void clear（）是什么？

选项1）删除所有对象

选项2）删除您的最后一个插入列表

选项3）删除重复对象

依旧......

当然这是一个简单的例子，您可以猜测clear（）的目标是选项1，但有时它会更复杂。

Answer 2

因为您必须明确指定界面背后的动机以及合同对调用者和实现者的意义。

也就是说，接口中的注释适用于两个受众：呼叫者和实施者。两者都应该意识到他们可以期待什么，他们应该如何表现。

显然，就像普通类一样，接口中的文档应遵循标准的JavaDoc规则。

Answer 3

Joshua Bloch（Effective Java） - 如果API可用，则必须记录

除非您记录您的界面方法，否则其他人（API用户）将不会知道 -

1. 它的作用（不是 它的作用）
2. 其前提条件
3. 其后置条件
4. 其副作用
5. 其线程安全

有效的Java - 第44项说：

  

方法的文档评论应简明扼要地描述合同   方法与其客户之间。

<小时/> 使用{@inheritDoc}记录界面方法还有一个额外的优势：继承。

有效的Java - 第44项说：

  

Javadoc具有“继承”方法注释的能力。如果是API   元素没有doc注释，Javadoc搜索最多   特定适用的文档注释，优先考虑接口   超。搜索算法的细节可以在The中找到   Javadoc参考指南[Javadoc-ref]。你也可以继承部分   来自使用{@inheritDoc}标记的超类型的doc注释。这意味着，   除其他外，该类可以重用来自的文档注释   他们实现的接口，而不是复制这些注释。这个   设施有可能减轻维修负担   多套几乎相同的文档评论

Answer 4

简单。因为，我们需要为实现这些接口的Java开发人员提供提供信息的接口的javadoc。