Julien crafts software at Zengularity. He likes designing code at the right level of abstraction. During his spare time, he also contributes to open source projects like the Play framework.
You write a Web service. You need to document the structure of the JSON blobs used by your API. You realize that this documentation must be consistent with your JSON protocols and that you don’t want to maintain both separately. Instead, you’d like to derive the documentation from the implementation of the protocols. How to achieve that?
I will present some technical approaches to solve this problem, digress about type classes, algebraic data types and the expression problem, and eventually end up with a simple yet powerful solution to get documentation consistent with the implementation.