Search code examples
javaeclipsegenericsjavadoccheckstyle

Generic type <P> converted to paragraph tag in Javadoc

I have a Java class with a generic type P. I want to document it in Javadoc. Normally I just do this:

/**
 * ...
 * @param <P> the type of publisher
 */

This shows up fine in actual Javadoc. However, CheckStyle is warning me that I need to document the type P because it renders <P> as a HTML paragraph. Also, the Eclipse formatter interprets it as a paragraph as well, so it messes up the formatting.

Is there a better way of documenting type parameters with type P? I know I can disable the Eclipse formatter to no longer auto format javadoc, but I'd rather not (and it wouldn't solve the checkstyle problem anyway).

I also know I can just rename P to something else, but given the number of generic types I am working with here, it would make things a lot less readable.

Solution

  • FOR POSTERITY: Turns out Checkstyle handles it just fine. The problem is that the whitespace added by the Eclipse formatter made Checkstyle (reasonably) argue that the Javadoc was incorrect. I also found an existing bug report for this bug in Eclipse: https://bugs.eclipse.org/bugs/show_bug.cgi?id=121728