在Java软件中，有几条指导原则可能会使我们的文档评论与第三方开发者的评论不同。我们的文档评论定义了官方的Java平台API规范。为此，我们的目标受众是除开发人员之外编写Java兼容性测试，或者符合或重新实现Java平台的人员。我们花时间和精力专注于指定边界条件，参数范围和角落案例，而不是定义常见的编程术语，编写概念性概述，并包括开发人员的示例。

编写文档注释有几种方式

因此，通常有两种不同的方式来编写文档注释-作为API规范，或编程指南文档。以下部分将介绍这两个目标。拥有慷慨资源的员工可以将两者融合到相同的文档中(正确地“分块”);然而，我们的优先事项决定我们主要关注在doc注释中编写API规范。这就是开发人员经常需要转向其他文档的原因，例如Java SE技术文档和用于编程指南的Java教程。

编写API规范

理想的情况下，Java API规范包含了执行Java平台的“一次编写，随处运行”的洁净室实现所需的所有声明-这样任何Java小应用程序或应用程序都将在任何实现上运行相同的声明。这可能包括文档注释中的断言以及任何架构和功能规范(通常用FrameMaker编写)或任何其他文档中的断言。这个定义是一个崇高的目标，并且我们可以充分指定API有一些实际的限制。以下是我们试图遵循的指导原则：

Java平台API规范由源代码中的文档注释以及标记为可从这些评论获得的规范的任何文档定义。

请注意，规范不需要完全包含在doc注释中。特别是，冗长的规格有时最好格式化在一个单独的文件中并链接到文档评论。

API规范是调用者和实现之间的契约。

规范描述了调用者可以依赖的每个方法的行为的所有方面。它没有描述实现细节，例如方法是本地的还是同步的。规范应该描述(文本)给定对象提供的线程安全保证。在没有明确的相反指示的情况下，假定所有对象都是“线程安全的”(即，允许多个线程同时访问它们)。人们认识到，目前的规格并不总是符合这种理想。

除非另有说明，否则Java API规范声明需要与实现无关。例外情况必须明确标明。

我们有如何突出记录实施差异的指导原则。

Java API规范应包含足以使软件质量保证能够编写完整的Java兼容性工具包(JCK)测试的断言。

这意味着文档评论要满足SQA一致性测试的需求。这些评论不应该记录错误或者当前超出规范的实现如何工作。

编写编程指南文档

将API规范与编程指南区分开来的例子有：常用编程术语的定义，某些概念概述(比如隐喻)，以及实现错误和解决方法的描述。毫无疑问，这些有助于开发人员的理解，并帮助开发人员更快地编写可靠的应用程序。但是，因为这些不包含API“断言”，所以它们在API规范中不是必需的。您可以将任何或所有这些信息包含在文档注释中(并且可以包含 自定义标签，由一个自定义doclet处理，以促进它)。在Java软件中，我们有意识地不在文档注释中包含此级别的文档，而是包含指向此信息的链接(指向Java教程和更改列表的链接)，或者将此信息包含在与API规范相同的文档下载包中- JDK文档包包含API规范以及演示，示例和编程指南。

进一步详细了解如何记录错误和解决方法很有用。有时有怎样的代码之间的差异应该工作以及如何实际工作。这可以采取两种不同的形式：API规范错误和代码错误。最好决定是否要在文档注释中记录这些内容。在Java软件中，我们决定在doc评论以外的文档中记录这两者，虽然我们确实有例外。