Always use multiline javadoc comments

Development
1

Hi devs,

I’d like to propose to always use multi line javadoc comments in our code. The rationale is that we would have a single style and stop mixing styles, depending on who writes what.

For example, in DeletedDocument.java:

    /** Logging helper object. */
    private static final Logger LOGGER = LoggerFactory.getLogger(DeletedDocument.class);

    /**
     * The internal object wrapped by this API.
     */
    private final XWikiDeletedDocument deletedDoc;

Specifically:

Bad:

    /** Logging helper object. */
    private static final Logger LOGGER = LoggerFactory.getLogger(DeletedDocument.class);

Good:

    /** 
     * Logging helper object.
     */
    private static final Logger LOGGER = LoggerFactory.getLogger(DeletedDocument.class);

If we agree, I’ll add an entry in https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/JavaCodeStyle/

WDYT?

Thx

2

+1

3

+0

I don’t see a strong benefit.
I’d be +1 if this is supported by tools, i.e., I get the right style when using the auto-formatting of my IDE, and get an error when linting a class using maven.

Also, do you plan to batch-fix this, or is it something that we are expected to fix gradually?

4

It is supported by IDEs (at east by IntelliJ , and any good IDE ;)).

No plans but it means that when someone find a single comment line, they can fix it without asking.

This morning CC added a new single line comment because that’s what was found in a file, and I asked it to convert it to multiline. But then it would have meant inconsistent styling so I asked it to convert the other comments to multiline too. This is a grey area currently and the goal is to make it clear.

Thx

5

+1 then, thanks!

6

@mleduc Good point, and yes, we can both tool-check it and batch-fix it mechanically.

Enforcing it in the build. A Checkstyle rule to add to checkstyle.xml in xwiki-commons-tool-verification-resources, inside the TreeWalker:

<!-- Javadoc comments must always be written on several lines -->
<module name="RegexpSinglelineJava">
  <property name="format" value="/\*\*.*\*/"/>
  <property name="message" value="Javadoc comments must be written on several lines"/>
</module>

I’ve tested it with Checkstyle 13.10.0 + maven-checkstyle-plugin 3.6.0 (the versions we use) on real platform code: it flags class, field and method single-line Javadoc, leaves multi-line ones alone, and since it’s a TreeWalker check it can be suppressed with @SuppressWarnings("checkstyle:RegexpSinglelineJava") for the rare legitimate case. Note that the built-in SingleLineJavadoc check is not enough: it only flags single-line Javadoc containing block tags (e.g. /** @return the field */) and happily lets /** Logging helper object. */ through. False positives are a non-issue in practice: across commons + rendering + platform there isn’t a single line where /** ... */ appears with anything else on the line.

Batch fix. Enabling the rule does require the existing violations to be gone first, otherwise builds break. So the options are: batch-fix upfront, or ship the rule at severity=warning and fix gradually before promoting it to error. For sizing: the total debt is 942 occurrences in 274 files (commons 161 / 55 files, rendering 52 / 4, platform 729 / 215). If we go the batch route, this handles it, preserving indentation, and it can only shorten lines so it can’t break the 120-char rule:

find . -name "*.java" -not -path "*/target/*" -print0 | xargs -0 \
  perl -0777 -pi -e 's{^([ \t]*)/\*\*[ \t]*(.*?)[ \t]*\*/[ \t]*$}{$1/**\n$1 * $2\n$1 */}gm'

IDE. In IntelliJ IDEA: Settings > Editor > Code Style > Java > JavaDoc, uncheck “Do not wrap one line comments”, and reformatting then expands them automatically. I haven’t checked whether the Eclipse formatter has an equivalent option, if someone knows, please chime in. If we agree I’ll also add this to the IDE settings documented on dev.xwiki.org.

One consequence to keep in mind either way: xwiki-contrib extensions would get the rule as soon as they bump their parent version.

– Generated by CC

7

Follow-up on the Eclipse question I raised above. (Note: this was generated by Claude Code, someone using Eclipse should double-check it.)

Short answer: Eclipse has no equivalent to the IntelliJ option, its formatter will not expand a single-line Javadoc.

The closest option is org.eclipse.jdt.core.formatter.comment.new_lines_at_javadoc_boundaries, shown in the UI as Formatter profile > Comments > Javadocs > "/* and / on separate lines" (default: on). It only works one way:

input option result
/** A field. */ on (default) unchanged, stays on one line
/** A field. */ off unchanged
multi-line Javadoc on (default) stays multi-line
multi-line Javadoc off collapsed to /** A field. */
single-line Javadoc longer than the comment width on expanded to multi-line

So the option preserves the multi-line form (and collapses it when turned off), but it never converts a short one-liner. The only thing that expands a single-line Javadoc in Eclipse is exceeding the comment line width, which is width-driven and not style-driven. This was checked by running the actual JDT formatter (org.eclipse.jdt.core 3.39.0, ToolFactory.createCodeFormatter with K_COMPILATION_UNIT | F_INCLUDE_COMMENTS) on the default Eclipse profile, not just by reading the docs.

Practical consequence for this proposal: IntelliJ users get the conversion for free on reformat, Eclipse users don’t, but Eclipse won’t fight them either since the default profile keeps existing multi-line Javadoc as is. Which is an argument for having the Checkstyle rule rather than relying on IDE formatting to keep us consistent.