In general I support the idea of documenting data structures rather than (or in addition to) code. But I think that your proposal still needs some work. I did a first pass on the first commit in order to outline what I think the philosophy of this kind of comments should be, so there can be some discussion.