Improve the documentation on how IntSet is represented

[wrengr]

The current comments/documentation on the internal representation of IntSet are poorly/confusingly phrased. This should be fixed to ease introducing future developers.

[m-renaud]

Thoughts on this being a README in the Data/IntMap/ directory (in addition to better comments in code)? That may make it easier to format and add graphics to help with the explanation. I can put something together since I've been digging around in the code a little bit.

[treeowl]

A README sounds okay, but there will need to be a strongly worded note in the code reminding people to update it whenever the structure or invariants change. Also, I think improving the comments remains a priority regardless.

…

On Dec 22, 2017 1:15 PM, "Matt Renaud" ***@***.***> wrote: Thoughts on this being a README in the Data/IntMap/ directory (in addition to better comments in code)? That may make it easier to format and add graphics to help with the explanation. I can put something together since I've been digging around in the code a little bit. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#404 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABzi_cLETB4T7gap2ksyhI4ACL14E_1Nks5tC_HcgaJpZM4L__QD> .

[meooow25]

The documentation got some attention in #998, so we should be good for now. The details can be found under

containers/containers/src/Data/IntSet/Internal.hs

Line 282 in dc98ae7

-- Note [IntSet structure and invariants]