Generic type <P> converted to paragraph tag in Javadoc

Question

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.

Answer 1

This is a bug in CheckStyle.

The official Javadoc documentation says that notation is correct:

Example of a type parameter of a class:

 /**   * @param <E> Type of element stored in a list   */ 

If you're stuck with this version of CheckStyle, then the only way to satisfy both constraints is to rename your P type parameter to something else.

Answer 2

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