以下是 Java 文档注释的一些基本规则和用法：
1. 注释格式：
Java 文档注释以 /** 开始，以 */ 结束。注释内容可以包含多行描述，使用标签来标识不同的注释元素。
/**
* This is a sample class that demonstrates Java documentation comments.
*
* @author Your Name
* @version 1.0
* @since 2023-01-01
*/
public class SampleClass {
// Class code here
}
2. 常用标签：
- @param：描述方法的参数。
- @return：描述方法的返回值。
- @throws 或 @exception：描述方法可能抛出的异常。
- @see：引用其他类、方法或相关文档。
- @deprecated：标记已过时的类、方法或字段。
/**
* Calculates the sum of two numbers.
*
* @param num1 The first number.
* @param num2 The second number.
* @return The sum of num1 and num2.
* @throws IllegalArgumentException If either num1 or num2 is negative.
* @deprecated Use {@link #calculateSum(int num1, int num2)} instead.
* @see Math#addExact(int, int)
*/
public int addNumbers(int num1, int num2) throws IllegalArgumentException {
// Method implementation here
}
3. 生成文档：
使用 Javadoc 工具生成文档非常简单。可以在命令行中使用以下命令：
javadoc YourClass.java
或者在集成开发环境（IDE）中使用相应的工具选项。生成的文档将在指定目录下生成一个 index.html 文件，其中包含了类、方法、字段等详细的文档信息。
4. 注意事项：
- 文档注释应该详细、清晰，以便其他开发者理解和使用你的代码。
- 注释中的标签（@param、@return 等）通常应该以小写字母开头，但是对于 @param 标签中的参数名，可以保持和代码一致的风格。
- 尽量避免在文档注释中使用 HTML 标签，以保持文档的纯文本形式。
文档注释是编写可读性和可维护性代码的重要组成部分，也是共享代码的文档的一种重要方式。在编写代码时，及时添加并维护好文档注释，有助于提高代码的质量和协作效率。
转载请注明出处：http://www.pingtaimeng.com/article/detail/13502/Java