Add explanations / reasoning to the bug patterns

[philipp-paland]

Problem

When I look at the documentation of a bug pattern, I can see what the pattern is / wants to enforce, but not why that is better.

Example: https://error-prone.picnic.tech/bugpatterns/AmbiguousJsonCreator/ - I understand that "JsonCreator.Mode should be set for single-argument creators", but I don't know why.

Description of the proposed new feature

Add a section to the documentation of each bug pattern that explains why it's better to follow the rule. Compare with Sonar rules which usually explain the reasoning behind themselves quite well: https://rules.sonarsource.com/java

[philipp-paland]

Even error prone itself has better explanations typically, for example: https://errorprone.info/bugpattern/DeadException

[Stephan202]

Hi @therealppa! Thanks for the feedback; indeed we should do better in this regard. We're working on several initiatives to derive better documentation from the code; that should make it easier to maintain the docs. (That said, I see that in this case the code doesn't explain the issue at hand, either; I'll try to dig that up.) I'll leave this issue open for now, until we've reached a hopefully-acceptable baseline.

NB: I see that you're working for @foryouandyourcustomers; if you happen to see Jens Plattfaut, say hi ;)

[philipp-paland]

Thanks @Stephan202 - I'll say hi when I next see him :)