Luke_P Luke_P - 1 month ago 5
Java Question

check style error when parsing javadoc

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 :)

Answer

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).