singletons icon indicating copy to clipboard operation
singletons copied to clipboard

Improve documentation of Data.Singletons

Open tomjaguarpaw opened this issue 8 months ago • 11 comments

Currently I would say that singletons is daunting. This should not be! The underlying principle is straightforward. It took me a long time to understand it, but now that I understand it, it's simple 😂 Now, I did have to pretty much reinvent it before I could understand it. I lay the blame at the feet of the documentation.

There are substantial changes that could make the documentation more approachable. This PR is a small effort in that direction. It contains two minor Haddock fixes, and a pervasive change which I hope will improve the situation a lot:

Don't think of Sing/SingI as indexed by a type of a given kind, think of it as indexed by a value of a given type.

This PR changes the variable k to t in many places to aid this change in thinking.

I really don't think it's helpful to look at the below case statement and interpret b as a variable standing for something of kind Bool, either type True or type False. That may or may not be technically correct (I don't know) but I think it is far more helpful for the intuition if I think of it as something of type Bool, either value True or value False, just used at the type level.

case sing @b of
  STrue -> ...
  SFalse -> ...

I think this way of thinking, encouraged by the notation in this PR, would go a long way to resolving the kinds of difficulties we see in, e.g. https://github.com/goldfirere/singletons/issues/260#issuecomment-1353244384

What do you think? I have a number of other suggestions for documentation improvements if you like this one.

tomjaguarpaw avatar Jun 01 '24 13:06 tomjaguarpaw