Clearly, I read through the docs too quickly. The comments are an improvement. I do wonder though if some examples in the docs would be a good idea.