singletons
singletons copied to clipboard
Improve documentation of Data.Singletons
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.