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.

Thanks!

I remembered once I drew ASCII diagrams for a particularly tricky algorithm in the top of its unit test methods. And people indeed deleted them.