如何写java文档

转发自IBM web Site 编制 Java 成员函数文档		英文原文

代码头的重要性 Scott W. Ambler 总裁，Ronin International 2000 年 8 月 17 日 请尝试这些针对编制 Java 成员函数文档时要包括的内容的建议。 每个 Java 成员函数都应该在对于理解函数至关重要的所有信息进行文档编制的源代码顶部包括某种头，称为成员函数文档。该信息包括（但不限于）下面这些建议。 成员函数所做的事情以及这样做的理由 通过对成员函数所做的事情编制文档，其他人就可以更容易地确定他们是否可以重用您的代码。 该文档使其他人更容易地将您的代码放入上下文中。 还可以使其他人更容易地确定是否应该实际对他们的一段代码进行一个新的改动（或许新改动的理由 与最初编写该代码的理由冲突）。 哪些成员函数必须作为参数传递 您还需要表示将如何使用成员函数的任何参数。 该信息能让其它程序员知道传给成员函数的是什么。javadoc @param 标记用于这一目的。 成员函数返回什么 您需要对成员函数返回的内容（如果有的话）编制文档， 以便其它程序员可以正确地使用返回值或对象。@return 标记用于此目的。 已知错误 应当对成员函数的任何未解决的问题编制文档，以便其它开发人员理解成员函数的缺点和难点。 如果某一特定的错误可适用于一个类中的多个成员函数，那么应该针对该类而不是单独为该函数编制文档。 成员函数带来的任何异常 您应该对成员函数向您掷出的所有异常编制文档，以便其它程序员知道他们的代码将需要捕捉什么。javadoc @exception 或 @throws 标记用于此目的。 可见性决定 如果您觉得其它开发人员会怀疑您对成员函数选择的可见性——或许在其它对象调用该成员函数之前，您已经使该成员函数变成公共的——您应该对您的决定编制文档。 这会使其它开发人员搞清楚您的思想，这样他们就不会把时间花费在思考您的操作上。 成员函数如何更改对象 如果成员函数更改对象，则这需要指出。 例如，银行帐户的 withdraw() 成员函数修改帐户余额。 该信息让其它 Java 程序员确切地知道成员函数调用将如何影响目标对象。 如何在适当时调用成员函数的示例 确定一块代码如何工作的最容易方法之一就是看一下示例， 所以包括如何调用成员函数的一个或两个示例是十分有用的。 可适用的前提条件和后置条件 前提条件是成员函数正确操作的约束， 而后置条件是在成员函数完成运行后是否为真的特性或断言（请参阅参考资料中的 Object-Oriented Software Construction）。 通过用许多方式，前提条件和后置条件描述了当编写成员函数以及确切地定义如何使用成员函数的条件时所做的假设（请参阅参考资料中的 Building Object Applications that Work）。 所有并发性问题 对于许多开发人员来说，并发性是一个新的且复杂的概念，而对于有经验的并发程序员来说，最多只是一个旧的且复杂的主题。 最终结果是，如果使用 Java 编程语言的并发编程特性，则需要彻底地对它们编制文档。Doug Lea（请参阅参考资料中的 Concurrent Programming in Java）建议， 当类包括同步和非同步成员函数时，特别是当它需要自由的访问权以允许其它开发人员安全地使用这些成员函数时，必须写出成员函数所依赖的执行上下文编制文档。如果实现 Runnable 接口的类的 setter（更新字段的成员函数）没有同步，则应该写明原因。 最后，如果覆盖或过载成员函数并更改其同步，则也应该写明原因。 文档示例 图 1 描述了一个 Java 成员函数头的文档示例。请注意我是如何应用标准的 javadoc 标记（如 @return）和非标准的 javadoc 标记（如 @precondition）的。 要支持这些新标记，我将需要开发识别它们的 doclet 或者采购可以定制以识别它们的 Java 开发工具。 图 1. 成员函数头文档示例 /** Withdraw the funds from this account. @param amount The amount of the withdrawal. @return The amount withdrawn. @precondition The account must have the funds available for them to be withdrawn. @postcondition If the funds are available they will be withdrawn and a record of the withdrawal will be made. @throws InsufficientFundsException An indication that the account balance and overdraft limit were not sufficient to allow the withdrawal to occur. @modifies Yes Debits the funds and posts a record into the account transaction history. @concurrency Changes to an account balance, such as a withdrawal, must occur as an ACID transaction.*/ 重要的事情是，仅当能使代码更清晰时，才应该对它编写文档。 对于每一个成员函数，将不对上述的所有要素编制文档，因为不是所有要素都可适用于每个成员函数。 然而，将对您编写的每个成员函数的其中几个要素编制文档。 参考资料 有关记录 Java 成员函数的详细信息，请参阅： Building Object Applications That Work: Your Step-By-Step Handbook for Developing Robust Systems with Object Technology，由 Scott Ambler 著。 The Object Primer 2nd Edition，由 Scott Ambler 著。 Concurrent Programming in Java: Design Principles and Patterns，Doug Lea 著 Object-Oriented Software Construction, Second Edition