Hi all,

I'm working on a library that uses quite a lot of type "magic" (as some would call it), but really it's all just implementation details. The type families are necessary for me to write the code, but an outside understanding of these type families shouldn't be necessary to understand the library. Unfortunately, Haddock does not align with that goal. To give you a feeling for things, take the following types:

data Expr (t :: k)
data AsHaskell (t :: k)

data BaseType = DBInt | DBText

type family Col (f :: k -> *) (a :: k) :: *
type instance Col Expr (a :: BaseType) = Expr a
type instance Col AsHaskell (a :: BaseType) = BaseTypeAsHaskell a

type family BaseTypeAsHaskell (bt :: BaseType) :: * where
BaseTypeAsHaskell 'DBInt = Int
BaseTypeAsHaskell 'DBText = String

class Lit (exprType :: k) where
lit :: Col AsHaskell exprType -> Expr exprType

instance Lit 'DBInt where lit = ...
instance Lit 'DBText where lit = ...

(I am modelling the interaction with remote relational databases, to provide a little more context)

Now when I export this, I end up with the following:

Fine, not much needs to change there. Haddock now also gives me specialised types for instances, but these don't go far enough:

Instances

Lit BaseType DBInt
Methods lit :: Col (TYPE Lifted) DBInt (AsHaskell DBInt) exprType -> Expr DBInt exprType

But this is considerably less helpful:

First, it seems to be broken, as it mentions the exprType variable, when is just DBint.

Secondly, it mentions all sorts of kinds which are, in my opinion, unreadable in the current form.

All of these problems would be solved if we just normalised this type family application as far as possible. What I really want to export is:

Instances

Lit DBInt
Methods lit :: Int -> Expr DBInt

This is the type I want my users to be aware of.

Has this been discussed before? If not, how do people feel about this?

Ollie