The documentation for JSON parsing in Play is hilarious.
You read the "The Play JSON library Basics" document, it looks like a lot of code for something that should be simple, but you go ahead and implement as explained. After a while, the verbosity starts bugging you, so you read the "JSON Reads/Writes/Format Combinators", followed by "JSON transformers" and finally the "JSON Macro Inception" pages.
The punchline in the last section can be summarized as "forget all that other stuff, just do "implicit val personFmt = Json.format[Person]". I was happy to be able to delete hundreds of lines of code from my project after learning this, but couldn't you just have told me this upfront since it probably covers 99% of all cases? The documentation also has an aura of "Isn't this all very clever?" feeling to it. It's also quite hard to search for anything, as outdated versions of the docs keep popping up in Google as the first results.
I think if anything that example shows the cleverness is a good thing. It's from almost 5 years ago, since when Scala has gone from strength to strength, so the collections rewrite turned out quite well, and fears that it would stop new people coming to Scala, or that companies would stay on 2.7 and the community would schism, were definitely unfounded. The "use case" simplification of the documentation has been implemented and has shown itself to work well, suggesting that this kind of complexity can be managed. And a few years later I've seen Chris use equally complex techniques in his own code (check out his "practical scalaz" talk).
I had this exact same thing experience, thinking, "wow, they want me to write marshal/unmarshal code for every type... is it 1999?" and then, finally, stumbling across the horrifically written "JSON Macro Inception" articles--as if no one had ever used reflection before for serialization--and feeling very, very stabby.
And lets not talk about all the wrong/missing import statements in code examples...
The documentation also has an aura of "Isn't this all very clever?"
This attitude needs to die. Forever. Why the fuck should I need know about contravariance and parser combinators to write a basic web app? I hope this Scala forking will kill it in Typesafe. It has no place in actually building products.
Yes. The implementation uses a macro, which some people have (sometimes legitimate) concerns about, but you can tell it to make a format for a case class and it will Just Work.
You read the "The Play JSON library Basics" document, it looks like a lot of code for something that should be simple, but you go ahead and implement as explained. After a while, the verbosity starts bugging you, so you read the "JSON Reads/Writes/Format Combinators", followed by "JSON transformers" and finally the "JSON Macro Inception" pages.
The punchline in the last section can be summarized as "forget all that other stuff, just do "implicit val personFmt = Json.format[Person]". I was happy to be able to delete hundreds of lines of code from my project after learning this, but couldn't you just have told me this upfront since it probably covers 99% of all cases? The documentation also has an aura of "Isn't this all very clever?" feeling to it. It's also quite hard to search for anything, as outdated versions of the docs keep popping up in Google as the first results.