4

I'm slowly trying to introduce checkStyle checks for javadocs in an existing code base.

It seems like every time it encounters a parameter (@param or @return) which describes a list, map etc.. It fails to parse the code and throws an error, does anybody have any idea how to prevent this??

for example: 

  /**
   * 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 {}

so it cannot parse 

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

and creates the error: 

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.

This happens when trying to apply different checks and this jdoc does/should pass the checks.

any help would be great :)

gar
  • 14,152
  • 5
  • 30
  • 31
Luke_P
  • 659
  • 2
  • 7
  • 23

2 Answers2

4

As per the Javadoc specification, @return does not include the type of the returned value. You simply add a description of what is returned after @return. If you want to include the type, it is part of the description and thus HTML characters such as < need to be escaped (&gt;). A better option would be something like:

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

(You cannot link to parameterized types, but should instead link to both the generic type and the parameter type).

Markus Fischer
  • 1,326
  • 8
  • 13
2

You should probably escape < and > so that it is not considered an XML tag, like &lt; and &gt;. See this question too How can I use "<" and ">" in javadoc without formatting?

Community
  • 1
  • 1
Danil Gaponov
  • 1,413
  • 13
  • 23
  • yep,but the problem is I do not want this comment to be considered as HTML. ideally I don't want to change the code ( which is valid ) , I want to adjust the checkstyle configuration (somehow) to allow this. Thanks anyway :) – Luke_P Nov 03 '16 at 11:27
  • This is not a valid Javadoc, I believe. So you will have to disable the Javadoc checks in checkstyle completely. – Danil Gaponov Nov 03 '16 at 11:29
  • Ok, Your right :) :( . I think the solution is "* \@return \@code List the people we are interested in." Doesn't look good tho (clean code style). – Luke_P Nov 03 '16 at 11:56