Java 文档 (Javadoc) 最佳实践

• 公共和受保护成员应使用 Javadoc 注释进行文档记录。
• 也建议对包私有和私有成员进行文档记录，尤其是在它们复杂或不言自明的情况下。
• Javadoc 注释的第一句是摘要描述。它应简明扼要地概述方法的功能，并以句号结尾。
• 对方法参数使用 @param。描述以小写字母开头，不以句号结尾。
• 对方法返回值使用 @return。
• 使用 @throws 或 @exception 记录方法抛出的异常。
• 使用 @see 引用其他类型或成员。
• 使用 {@inheritDoc} 从基类或接口继承文档。
  • 除非行为发生重大变化，在这种情况下，您应该记录差异。
• 对泛型类型或方法中的类型参数使用 @param <T>。
• 使用 {@code} 标记内联代码片段。
• 使用 <pre>{@code ... }</pre> 标记代码块。
• 使用 @since 指示功能引入的时间（例如，版本号）。
• 使用 @version 指定成员的版本。
• 使用 @author 指定代码的作者。
• 使用 @deprecated 将成员标记为已弃用并提供替代方案。