Single line JavaDoc comments with a block tag should not be formatted into one line.
devesh opened this issue · comments
Rule 7.1.1: https://google.github.io/styleguide/javaguide.html#s7.1.1-javadoc-multi-line
The basic form is always acceptable. The single-line form may be substituted when the entirety of the Javadoc block (including comment markers) can fit on a single line. Note that this only applies when there are no block tags such as @return.
google-java-format currently incorrectly formats a JavaDoc with a single block tag line into a single line like so:
/** @author author */
The summary fragment is required: https://google.github.io/styleguide/javaguide.html#s7.2-summary-fragment, so that example is already in violation of the style guide.
Previously: #193
This JavaDoc is a tricky exception to an exception. It's for a class that isn't required to have JavaDoc, so rule 7.3.4 says that rule 7.2 doesn't apply, but rule 7.1.1 still applies.
Rule 7.1.1 seems to anticipate this case by noting that shortening to a single line shouldn't happen when there is a block tag, but its example is bad. The example uses @return, but that tag is used as an example in 7.2 as one that should be removed for single line comments.
Thanks, I'll follow up on whether that's the intent, that 7.1.1 is more strictly enforced than 7.2 for non-required javadoc.
Also the guide doesn't ever require the single line form, this is one of the places where google-java-format chooses one of several options allowed by the style guide and then tries to apply it consistently. We could consider not using the single-line form for javadoc with a missing summary fragment, and that could be helpful if it draws attention to the missing summary fragment or makes it easier to edit the comment to insert it.
The implementation has been updated to format javadoc with missing summary fragments on multiple lines: 668f108
The next version of the style guide will probably have 7.3.4 include 7.1.1 in the list of things that can be relaxed for non-optional javadoc, so the intent isn't that /** @author author */ is less correct than multiple lines on non-required javadoc
One benefit of leaving it on multiple lines is that it may draw attention to missing summary fragments and make it easier to add them when they're missing
Thanks! This new formatting makes sense.