Support re-writing multiline docstrings into their multiline form

[MGHawes]

I often wish that people would write something like:

    /** Returns true if the argument should be optional when fully parsed. */
    public static boolean optionalWhenFullyParsed(Argument<?, ?> argument) {
        return argument.isOptional() && argument.defaultValue().isEmpty();
    }

rather than:

    /**
     * Returns true if the argument should be optional when fully parsed.
     */
    public static boolean optionalWhenFullyParsed(Argument<?, ?> argument) {
        return argument.isOptional() && argument.defaultValue().isEmpty();
    }

We could compute whether it would fit on one line and rewrite it if it would. This would only apply to the case of multi-line docstrings that contain a single line. i.e. it would not include:

    /**
     * This is
     * a silly 
     * docstring.
     */
    public static boolean example()

[carterkozak]

I agree with your examples, however the trade-off is that it destroys helpful ascii diagrams embedded in javadoc. Verbose javadoc formatting is more common, but not terribly frictionful, where breaking spefically-formatted structures is less common, but much more frictionful when it occurs.

Our https://github.com/palantir/goethe wrapper around palantir-java-format for javapoet does format javadoc as you describe above, we have the capability, but I don't think the trade-off is correct to turn it on for human-authored code. What do you think?

[ash211]

FWIW the Google Java Style guide notes the existence of the single-line pattern but does not endorse it:

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.

https://google.github.io/styleguide/javaguide.html#s7.1.1-javadoc-multi-line

(I happen to prefer the single-line form)

google-java-format joins to a single line if it fits within 100 characters: https://github.com/google/google-java-format/blob/38de9c4e05bc871496c232c1ccbfc4be06a580e2/core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java#L395-L449

[ash211]

Probably ascii diagrams should be wrapped in <pre></pre> tags. Hopefully goethe leaves the contents of those alone?

[MGHawes]

Would this destroy an ascii diagram? Surely for it to be a diagram then it must be multiline? And if so then i think (as per my example above), we would not reformat something like:

    /**
     * This is
     * a silly 
     * docstring.
     */
    public static boolean example()

wdyt?