Java文档注释

Java文档注释是一种特殊的注释形式，可用于生成API文档。在Java中，每个类、方法、变量和常量都应该有注释，以便其他人可以理解代码的含义和使用方式。Java文档注释以“/**”开头，以“*/”结尾，中间可以包含多行注释。Java文档注释可以被Java编译器、代码编辑器和Java文档生成器等工具所识别。

Java文档注释的格式

Java文档注释应该包含以下内容：

• 摘要信息：包括类、方法、变量或常量的简要说明。
• 详细说明：包括有关该元素的详细说明，如用法、参数、返回结果等。
• 参数说明：对方法的参数进行详细说明。
• 返回值说明：对方法的返回值进行详细说明。
• 异常说明：对方法可能抛出的异常进行详细说明。
• 示例代码：包含该元素的一些示例代码，以便其他人可以更好地理解该元素的使用。

Java文档注释的格式如下：

/**
 * [摘要信息]
 *
 * [详细说明]
 *
 * @param [参数名] [参数说明]
 * ...
 * @return [返回值说明]
 * @throws [异常类名] [异常说明]
 * ...
 * [示例代码]
 */

一个Java文档注释的例子

下面是一个Java文档注释的例子：

/**
 * This class represents a bank account.
 *
 * A bank account contains a balance that can be
 * accessed and modified by depositing and
 * withdrawing money.
 *
 * Example:
 * <pre>
 * BankAccount account = new BankAccount();
 * account.deposit(100);
 * account.withdraw(50);
 * System.out.println(account.getBalance());
 * </pre>
 */
public class BankAccount {
    
    private double balance;
    
    /**
     * Creates a new bank account with a zero balance.
     */
    public BankAccount() {
        balance = 0;
    }
    
    /**
     * Deposits the given amount of money into this account.
     *
     * @param amount the amount of money to deposit
     * @throws IllegalArgumentException if the amount is negative
     */
    public void deposit(double amount) {
        if (amount < 0) {
            throw new IllegalArgumentException("Deposit amount cannot be negative");
        }
        balance += amount;
    }
    
    /**
     * Withdraws the given amount of money from this account.
     *
     * @param amount the amount of money to withdraw
     * @throws IllegalArgumentException if the amount is negative or greater than the balance
     */
    public void withdraw(double amount) {
        if (amount < 0) {
            throw new IllegalArgumentException("Withdrawal amount cannot be negative");
        }
        if (amount > balance) {
            throw new IllegalArgumentException("Insufficient funds");
        }
        balance -= amount;
    }
    
    /**
     * Returns the current balance of this account.
     *
     * @return the current balance
     */
    public double getBalance() {
        return balance;
    }
}

使用Java文档注释生成API文档

Java的标准工具包中包含有一个Java文档生成器工具——Javadoc，可以使用Java文档注释来生成HTML格式的API文档。

使用Javadoc生成API文档非常简单，只需要在命令行中输入以下命令即可：

javadoc [选项] [源代码文件/包名]

其中，选项可以是：

• -d：指定生成的文档输出目录。
• -sourcepath：指定搜索Java源代码文件的路径。
• -charset：指定文档编码。
• -classpath：指定类路径。
• -subpackages：指定包名（可以包含通配符）,并生成包内部及其子包的所有类的文档。

例如，以下命令将MyProject包中的所有类生成API文档，并输出到文档目录：

javadoc -d docs -sourcepath src -charset UTF-8 -classpath libs/* -subpackages MyProject

命令执行后，将在docs目录中生成HTML格式的API文档文件。

总结

Java文档注释是编写代码时非常重要的一部分，可以让其他开发者更好地理解代码的意图和使用方式。使用Java文档注释还可以生成API文档，方便开发者查阅API文档。因此，在编写Java代码时，务必要认真编写Java文档注释，并养成良好的注释习惯。