Again solution in the middle. When I wanna show how to use a piece of code, it is better to use it, so I suggest to show how to use the code in the unit tests. Maybe it is my workflow, but when I discover that I can't understand a class or how to use it (and I had some hard times reviewing some PR) I try to complement my understanding of reviewing the source code directly with the tests, because if they have been done properly the tests depicts the use of the class.