[DOCS] Improve documentation for @ToString

[michaelboyles]

Similar to #2870, which I also raised, I have an answer on Stack Overflow related to @ToString which I noticed has 9000 views. It seems to be the case that people are under the impression that it may be possible to change the format of the string generated by @ToString.

Since people are obviously searching for this a lot, I think it would be worth making it clearer in the documentation that this is not possible.

Current

Any class definition may be annotated with @ToString to let lombok generate an implementation of the toString() method. By default, it'll print your class name, along with each field, in order, separated by commas.

Suggested change

Annotating a class with @ToString will cause lombok to generate an implementation of the toString() method. There is configuration to specify whether field names should be included but otherwise the format is fixed: the class name followed by parentheses containing fields separated by commas, e.g. MyClass(foo=123, bar=234).

[rzwitserloot]

Could do. But we have some open issues on allowing you some flexibility. The problem is, the amount of use cases are staggering and it quickly spins out of control into something that takes 5 pages of manual and involves inventing a regex-like templating engine. All that just for some toString stuff. So we keep holding off.

Maybe you're right, and we should just update the docs now. We can always change it again if we do come up with a simple yet flexible solution.

[michaelboyles]

Yeah, could get complex. FWIW, I've always been perfectly happy with the format lombok spits out, and supporting a more specific set of use-cases seems beyond the scope of the problems lombok usually sets out to solve. Obviously if there's an elegant solution which increases flexibility without ballooning in complexity then everyone's happy.

I forgot to include the StackOverflow post in question. It's here: How to change the output of the method generated by Lombok's @ToString?