解析 javadoc 时检查样式错误答案

【问题标题】：check style error when parsing javadoc解析 javadoc 时检查样式错误
【发布时间】：2025-11-24 18:40:01
【问题描述】：

我正在慢慢尝试在现有代码库中引入对 javadocs 的 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 确实/应该通过检查时会发生这种情况。

任何帮助都会很棒:)

【问题讨论】：

标签： java javadoc checkstyle

【解决方案1】：

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

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

（您不能链接到参数化类型，而是应该链接到泛型类型和参数类型）。

【讨论】：

【解决方案2】：

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

【讨论】：

是的，但问题是我不希望这条评论被视为 HTML。理想情况下，我不想更改代码（这是有效的），我想调整 checkstyle 配置（以某种方式）以允许这样做。无论如何谢谢:)
我相信这不是一个有效的 Javadoc。因此，您必须完全禁用 checkstyle 中的 Javadoc 检查。
好吧，你的权利 :) :( 。我认为解决方案是“* \@return \@code List 我们感兴趣的人。”虽然看起来不太好（干净代码风格）。