Selena Selena - 4 months ago 15
Java Question

Getting undesired 'Property Summary" section when generating Javadoc

I have some methods with javadoc that are like the following:

/**
* Convenience method that determines whether this {@code ContextLink} links a {@code Property} or not.
* <p>
* If this {@code ContextLink}'s {@code ContextType} is anything other than {@code ContextType.GROUP}, it links a
* {@code Property}.
*
* @return {@code true} if the {@code ContextLink} links a {@code Property}, otherwise {@code false}
*/
public final boolean isProperty() {
return getType() != ContextType.GROUP;
}

/**
* Convenience method that determines whether this {@code ContextLink} links a {@code Property} with advanced
* behavior or not.
* <p>
* If this {@code ContextLink}'s {@code ContextType} is {@code ContextType.ADVANCED}, it links a {@code Property}
* with advanced behavior.
*
* @return {@code true} if the {@code ContextLink} links a {@code Property} with advanced behavior, otherwise
* {@code false}
*/
@SuppressWarnings("UnusedDeclaration")
public final boolean isAdvancedProperty() {
return getType() == ContextType.ADVANCED;
}

/**
* Convenience method that determines whether this {@code ContextLink} links a web application {@code Property} or
* not.
* <p>
* If this {@code ContextLink}'s {@code ContextType} is {@code ContextType.APPLICATION}, it links a web application
* {@code Property}.
*
* @return {@code true} if the {@code ContextLink} links a web application {@code Property}, otherwise
* {@code false}
*/
@SuppressWarnings("UnusedDeclaration")
public final boolean isApplicationProperty() {
return getType() == ContextType.APPLICATION;
}


When I generate the javadoc, I get a Property Summary section that I don't want. Instead of treating my methods as normal methods, they are treated to special handling that isn't appropriate. How do I prevent this without having to rename my methods so that they don't end in 'Property'? I have my own
Property class
that makes sense to be named that way because that is actually what it is called in our business domain glossary.

enter image description here

Answer

This is a bug in the Javadoc tool, more precisely in VisibleMemberMap#isPropertyMethod(MethodDoc).

When determining the list of methods that should be treated specially and turn up in the "Property Summary", Javadoc selects all methods that are visible, have a name ending with "Property", do not have any parameters, do not return void, and have name that does not start with "getX" or "setX" where X is any capital letter.

As there is special handling for getter and setter methods (the regular expression "[sg]et\p{Upper}.*" is used), I am convinced that this is a bug and whoever wrote this code forgot to also consider getter methods starting with "is".

I submitted a bug report to the JDK team explaining this problem and suggesting a simple fix (simply replacing the regular expression [sg]et\\p{Upper}.* abc with ([sg]et|is)\\p{Upper}.*. I will update this answer when this bug report gets a public bug ID assigned.

For the moment there are only two workarounds:

Fixing the problem in the Javadoc tool, recompiling Javadoc and using the patched version. This may not be viable if there is no way to control the environment in which the API docs are generated.

As an alternative, the boolean getter methods can be renamed to "getX" instead of "isX", but this might violate some naming conventions and is not valid for JavaBeans either. In addition to that, it would break compatibility with code that depends on the old name.

Another variant of the second solution is to rename the method so that it name does not end in "Property". For example "isPropertyAdvanced" instead of "isAdvancedProperty". However, this still leaves the problem with breaking existing code.

Update: Finally, the bug report got added to the public bug-tracking system. It has bug ID JDK-8161254