解析javadoc时检查样式错误

Question

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

似乎每次遇到一个描述列表，地图等的参数（@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确实/应该通过检查时会发生这种情况。

任何帮助都会很棒：）

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}

（您无法链接到参数化类型，但应该链接到泛型类型和参数类型）。