Javadoc“使用”部分 - 为什么缺少它？答案

【问题标题】：Javadoc "Use" section - why is it missing?Javadoc“使用”部分 - 为什么缺少它？
【发布时间】：2011-01-08 06:22:03
【问题描述】：

在 javadocs 中的一些 API（java.lang 和 java.util 之外）缺少 "Use" 部分。

XMLStreamReader 例如。有点令人不快的是，您无法根据 javadoc 判断 API 的哪些类返回您需要的类，并且您必须使用一些其他技巧（如 IDE 功能）来做到这一点。

是否有任何理由不在这些 API 中包含“使用”部分？

【问题讨论】：

【解决方案1】：

您为 XMLStreamReader 发布的链接是针对 http://java.sun.com/webservice 下的 javadocs，而不是针对核心 JavaSE API。

不过，XMLStreamReader in the core javadoc 的 javadoc 确实将“使用”部分填满。

至于为什么它们不同，我怀疑这只是一个质量控制问题。

【讨论】：

【解决方案2】：

像 javax.xml.stream.XMLStreamReader 这样的类是 Java extension 机制的一部分，因此可以用特定的实现替换它们（在这种情况下，如果我没记错的话，是 stax 的实现）。

您应该通过工厂方法获取实际的服务类，即使用两个公共类 XMLInputFactory 和 XMLOutputFactory。根据设计，您不需要知道实际的实现类是什么。

编辑：您为 XMLStreamReader 提供的链接来自 java 1.5 的 web-services 包。我不知道为什么缺少 use 部分，但不管它的价值如何，在 java se 6 api 中都包含它（参见here）。希望这会有所帮助...

【讨论】：

是的，但是在 API 中使用特别有用。 “另见”部分通常很有用，但并非总是如此。 XMLStreamReader 是 boostrap 类的一部分——它在 rt.jar 中
能否提供一个示例链接？也许我误解了您所指的“用途”是什么。