[Haskell-cafe] Could Haddock export documentation with type family applications normalised?

[Oliver Charles]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20160503/c7abc02d/attachment-0001.html>