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.