Add option to IDEA plugin (and CLI) to format JavaDoc #724

[blutorange]

As discussed in #724 (as I understand it), I added an option to the IDEA plugin to enable formattting JavaDoc comments.

• This adds an option to the IDEA plugin (checkbox) to format JavaDoc comments. It is disabled by default.
• As the IDEA plugin (sometimes) uses the bootstrapping formatter service, which in turn uses the command line tool, this also add an option --format-javadoc to the command line tool.
• To pass the options to the FormatterService loaded via service provider, I added a method withOptions to the service provided interface, which returns a new (immutable) instance with the updated options. Compared with the suggestion from the issue comment (Please expose option to format JavaDoc #724 (comment)), this (a) does not require deprecating methods and (b) the options can be set independently of where the formatter is actually used.
• Since the infrastructure to pass options to the formatter now exists, we could also add more options to the code style select configuration in the IDEA plugin, but I'm not sure if that makes sense (I want to use Palantir, after all).
• The issue also mentioned API compatibility. The service provider interface is compatible, most other classes and methods are internal. But if somebody more familar with the code base could take another look, that would be great.
• I also added a few tests for the new option.

Possible downsides?

• This adds an option that affects the formatter output, and Palantir strives to be an opinionated formatter without any configuration. As discussed in the issue, though, adding an option for fomatting JavaDoc should be ok.

[palantirtech]

Thanks for your interest in palantir/palantir-java-format, @blutorange! Before we can accept your pull request, you need to sign our contributor license agreement - just visit https://cla.palantir.com/ and follow the instructions. Once you sign, I'll automatically update this pull request.

[changelog-app]

Generate changelog in changelog/@unreleased

What do the change types mean?

• feature: A new feature of the service.
• improvement: An incremental improvement in the functionality or operation of the service.
• fix: Remedies the incorrect behaviour of a component of the service in a backwards-compatible way.
• break: Has the potential to break consumers of this service's API, inclusive of both Palantir services
  and external consumers of the service's API (e.g. customer-written software or integrations).
• deprecation: Advertises the intention to remove service functionality without any change to the
  operation of the service itself.
• manualTask: Requires the possibility of manual intervention (running a script, eyeballing configuration,
  performing database surgery, ...) at the time of upgrade for it to succeed.
• migration: A fully automatic upgrade migration task with no engineer input required.

Note: only one type should be chosen.

How are new versions calculated?

• ❗The break and manual task changelog types will result in a major release!
• 🐛 The fix changelog type will result in a minor release in most cases, and a patch release version for patch branches. This behaviour is configurable in autorelease.
• ✨ All others will result in a minor version release.

Type

• Feature
• Improvement
• Fix
• Break
• Deprecation
• Manual task
• Migration

Description

Add option to IDEA plugin (and CLI) to format JavaDoc #724

Check the box to generate changelog(s)

• Generate changelog entry

[blutorange]

@schlosna As far as I can see, the changelog needs to be generated by somebody with the proper permissions for this repo?

[blutorange]

Is there anything I still need to do before this PR can be considered for review?

[walles]

This branch has conflicts that must be resolved.

[blutorange]

Thanks for notifying me! I resolved the conflicts in case anybody wants to take a look at getting this merged.

[blutorange]

Is there any chance of getting this merged? Are you open to adding this option to the plugin or should I close this?

[blutorange]

Seems there are new merge conflict now that this PR has been around for so long. I can take a look at it, if there's any chance / interest in getting this merged? @crogoz

[ppkarwasz]

I’d really love to see this merged. I’m a big fan of the Palantir formatter: one of its biggest wins is that it ends discussions about style and formatting. With something like the Eclipse formatter, we’d still be arguing over trivial whitespace or line break options.

Unfortunately Javadoc-heavy PRs are still especially prone to bike-shedding over small details. Having this option would reduce noise, let contributors focus on real issues, and keep the style consistent without endless debates.

[awa-xima]

I can only second this. I write a lot of JavaDoc and my biggest pain is having to handle line breaks manually, which becomes annoying especially when you need to edit existing JavaDoc. We use spotless-maven-plugin to run palantir-java-format on commit, and I already added JavaDoc formatting to the spotless-maven-plugin. So at worst, I can just ignore line breaks and it will get formatted once I commit. But it would still be nice to see the formatting immediately in the IDE.

There are new releases all the time, but most seem to be auto releases. The most recent commits in this repo seem to be from @crogoz ? I'll take a look at fixing the merge conflicts if you'd be ok with adding this option?