docs: clarify how this compares to `google-java-format`

[rattrayalex]

In the README, there are some before/after examples, but it isn't clear whether that's comparing this library to the google version, or just to unformatted code.

It'd be great to see diffs between the two, and/or have a list of improvements you've made over the google one.

FWIW, my impression is:

1. This uses 4 spaces instead of 2.
2. This has much better style for builders.

I'd like to see this library become more popular!

[dan-lind]

Fully agree with this. Current docs only state that palantir builds on google-java-format, but as a potential user of palantir I would appreciate more hard facts about what I gain from using palantir over plain google-java-format

[iamdanfox]

it isn't clear whether that's comparing this library to the google version, or just to unformatted code.

I've just tweaked the README to clarify that the 'before' examples are how google-java-format prefers to lay out code, and we chose to build palantir-java-format in order to implement different heuristics (which produce the 'after' examples) #830.

Defer to current maintainers as to whether they want to invest in putting together a more extensive comparison/set of examples between the two projects.

From my recollection, the primary things we wanted to change from google-java-format were:

1. the way g-j-f handles lambdas
2. chained builder invocation containing very large arguments
3. method signatures (we wanted to prefer one line, then fall back to putting one line of arguments below the method name, then fall back to putting all arguments on separate lines)

We didn't really put together english descriptions of all the behaviour as it was being implemented (as many PRs included subtle behaviour changes we just considered 'better'). Example here: https://github.com/palantir/palantir-java-format/pull/71/files

I think the best way to evaluate this formatter against other formatters is to just try formatting your entire project locally and see if you consider the output to be net positive.

[rattrayalex]

Terrific, thank you!

FWIW, I thin your explanation here would also make a great addition to the README. Of course, at least now people who are really dedicated can find it easily, but putting that information in the README would probably make for even better marketing & adoption.

[koppor]

1. This uses 4 spaces instead of 2.

Note that you can configure google-java-format for AOSP style, which uses 4 spaces. (Which the gjf Eclipse plugin does not support yet - google/google-java-format#251)