I very much like your comment. It describes practical use of diagrams. In the past, I've included diagrams for a particularly complex state in the comment on top of my code. It certainly doesn't describe the whole system, or even the complete state of that code. And I expect that someone will delete the comment at some point. That's all fine.