Please expose option to format JavaDoc

[ChristianCiach]

In https://github.com/palantir/palantir-java-format/pull/152 you've disabled the formatting of JavaDoc by hardcoding a "false" value.

Google-Java-Format provides a command-line switch (and API) to enable/disable the formatting of JavaDoc. I would like you to do the same :)

[carterkozak]

This sounds reasonable to me, I've been meaning to add support for this feature to support our javapoet formatter, Goethe.

[ChristianCiach]

That being said, I am not sure about the API while keeping backwards compatibility.

In my eclipse-plugin I am currently using the ServiceLoader to retrieve an instance of com.palantir.javaformat.java.FormatterService, which is an interface with these two methods:

    ImmutableList<Replacement> getFormatReplacements(String input, Collection<Range<Integer>> ranges)
            throws FormatterException;

    String formatSourceReflowStringsAndFixImports(String input) throws FormatterException;

For keeping backwards compatibility maybe we should change these two methods to "default" methods to delegate to new methods that take an additional parameter boolean formatJavaDoc, like so:

    ImmutableList<Replacement> getFormatReplacements(String input, Collection<Range<Integer>> ranges, boolean formatJavaDoc);

    String formatSourceReflowStringsAndFixImports(String input, boolean formatJavaDoc) throws FormatterException;

    default ImmutableList<Replacement> getFormatReplacements(String input, Collection<Range<Integer>> ranges)
            throws FormatterException {
        return getFormatReplacements(input, ranges, false);
    }

    default String formatSourceReflowStringsAndFixImports(String input) throws FormatterException {
        return formatSourceReflowStringsAndFixImports(input, false);
    }

This way we could keep the old methods (maybe deprecating them).

[q3769]

#944

[ChristianCiach]

Thanks for notifying me. Closing this issue as done.

[q3769-patientpoint]

Thanks for notifying me. Closing this issue as done.

Sorry why is this one closed? It's not done.

There are couple of related issues: One is for Geothe, which is done; the other is for IntelliJ/idea plugin, which will most likely be automatically done if this current issue is worked on and completed.

My understanding of the current issue/request is to provide an option to enable Javadoc formatting on the CLI or core level, which is not done.

[ChristianCiach]

Oops, I didn't check. I thought this option was also exposed with the Idea plugin.

[blutorange]

One question just to make I did not misread this: the option to format JavaDocs should disabled by default, but we can add an option to other tools that make use of Palantir, e.g. diffplug/spotless#1995 ?

[q3769-patientpoint]

@blutorange: The request(s) by the original requester(s) was to add option to enable JavaDoc formatting; so yes, in that sense the default is "Javadoc formatting disabled".

However, if we are still accepting more votes/opinions on what should be the "reasonable default", then MHO is that the default should be "format-javadoc=true" and the (customization/configurable) option should be "format-javadoc=false".

Many thanks.

[blutorange]

Thanks for the info. For the time being I made a PR to add an option to the IDEA plugin (and CLI).

Personally, I'm not quite so fond of the way it formats doc comments, such as potentially long indents in @param or its liberal usage of self-closing tags. If I had to choose, I like the Eclipse formatter better for doc comments. In that regard, I can understand why some people would rather not have it be turned on by default. Still, it's not that bad and the formatted comments look mostly ok to me. Also, let's not forget, it's a great improvement over not formatting comments at all. Having to insert line breaks manually is quite cumbersome when you work a lot with doc comments.

Since we're probably going to enable JavaDoc formatting, we would not mind if it were turned on by default.