JavaDoc同一异常使用多个@throws标签的官方编码规范建议

工具兼容性说明 #

JavaDoc原生解析工具本身支持对同一异常类型使用多个@throws标签，编译生成文档时不会抛出错误，会将所有同类型标签的说明逐条展示在对应异常的文档条目下，不存在语法层面的兼容问题。

官方风格指南要求 #

Oracle官方发布的JavaDoc编写规范明确给出推荐写法：单个异常类型对应唯一的@throws标签。所有能触发该异常的场景，都需要合并到这一个标签的说明文本中，不建议将同类型异常拆分为多个@throws标签声明。
你学生代码里对IllegalArgumentException拆分两个标签的写法虽然能被工具识别，但不符合官方风格要求，标准合并写法参考如下：

/**
 * ...
 * @throws IllegalArgumentException 存在以下两类非法入参场景时抛出：
 * <ul>
 * <li>传入的棋盘行数、列数参数不符合合法取值范围</li>
 * <li>任一玩家配置的持棋类型为{@link Stone#None}</li>
 * </ul>
 * @throws IllegalStateException 两名玩家配置了相同的棋子颜色时抛出
 */
public void doSomething(...) { ... }

如果触发场景的说明文本较短，也可以不用列表，直接用分句衔接即可，比如：
@throws IllegalArgumentException 传入的行列参数不合法，或任一玩家持棋类型为{@link Stone#None}时抛出

行业通用编码约定 #

目前主流的Java企业级编码规范（包括Google Java编码规范、阿里巴巴Java开发手册等）均与Oracle官方要求对齐：

• 禁止为同一异常类型声明多个@throws标签，避免生成的API文档出现重复异常条目，增加使用者的查阅成本
• 单个@throws标签内的场景说明要清晰无歧义，场景较多时可以通过HTML无序列表做结构化展示，不要为了排版方便拆分标签
• 不同类型的异常必须分不同@throws标签声明，禁止将不同异常类的触发场景合并到同一个标签下

内容的提问来源于stack exchange，提问作者Markus Weninger