解析javadoc时检查样式错误

Question

我正在慢慢地尝试在现有代码库中引入对 javadoc 的 checkStyle 检查。

好像每次遇到描述list、map等的参数（@param或@return），解析代码失败，抛出错误，有人知道如何防止这种情况吗？

例如：

  /**
   * Process list of people.
   *
   * @param account the relevant account.
   * @return List<People> the people we are interested in.
   * @throws SQLException
   */
   private static List<People> getPeople(Account account) throws SQLException {}

所以它无法解析

* @return List<People> the people we are interested in.

并产生错误：

error: Javadoc comment at column 18 has parse error. Missed HTML close tag 'People'. Sometimes it means that close tag missed for one of previous tags.

当尝试应用不同的检查并且此 jdoc does/should 通过检查时会发生这种情况。

任何帮助都会很棒 :)

Answer 1

您可能应该转义 < 和 >，这样它就不会像 < 和 > 那样被视为 XML 标签。也看到这个问题How can I use "<" and ">" in javadoc without formatting?

Answer 2

根据Javadoc specification，@return不包括返回值的类型。您只需在 @return 之后添加对返回内容的描述。如果要包含类型，它是描述的一部分，因此需要转义 HTML 个字符，例如 < (>)。更好的选择是：

@return {@link List} of {@link People}

（您不能 link 参数化类型，而应该 link 泛型类型和参数类型）。

解析javadoc时检查样式错误

check style error when parsing javadoc

java

javadoc

checkstyle