<div dir="ltr">Hi all,<div><br></div><div>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:</div><div><br></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px"><div><font face="monospace, monospace">data Expr (t :: k)</font></div><div><font face="monospace, monospace">data AsHaskell (t :: k)</font></div><div><font face="monospace, monospace"><br></font></div><div><font face="monospace, monospace">data BaseType = DBInt | DBText</font></div><div><font face="monospace, monospace"><br></font></div><div><font face="monospace, monospace">type family Col (f :: k -> *) (a :: k) :: *</font></div><div><font face="monospace, monospace">type instance Col Expr (a :: BaseType) = Expr a</font></div><div><font face="monospace, monospace">type instance Col AsHaskell (a :: BaseType) = BaseTypeAsHaskell a</font></div><div><font face="monospace, monospace"><br></font></div><div><font face="monospace, monospace">type family BaseTypeAsHaskell (bt :: BaseType) :: * where</font></div><div><font face="monospace, monospace">  BaseTypeAsHaskell 'DBInt = Int</font></div><div><font face="monospace, monospace">  BaseTypeAsHaskell 'DBText = String</font></div><div><font face="monospace, monospace"><br></font></div><div><font face="monospace, monospace">class Lit (exprType :: k) where</font></div><div><font face="monospace, monospace">  lit :: Col AsHaskell exprType -> Expr exprType</font></div><div><font face="monospace, monospace"><br></font></div><div><font face="monospace, monospace">instance Lit 'DBInt where lit = ...</font></div><div><font face="monospace, monospace">instance Lit 'DBText where lit = ...</font></div></blockquote><div><br></div><div>(I am modelling the interaction with remote relational databases, to provide a little more context)</div><div><br></div><div>Now when I export this, I end up with the following:</div><div><br></div><div>Fine, not much needs to change there. Haddock now also gives me specialised types for instances, but these don't go far enough:</div><div><br></div><div><div style="margin:0px;padding:0px 0px 0px 2em"><p style="padding:0px 0px 0px 14px;font-weight:bold;color:rgb(78,98,114);font-family:sans-serif;font-size:13px;line-height:18.2px;background-image:url();background-position:0px 0.4em;background-repeat:no-repeat">Instances</p><div style="margin:0px;padding:0px;display:inherit;font-family:sans-serif;font-size:13px;line-height:18.2px"><table style="margin:0px;padding:0px;font-size:inherit"><tbody style="margin:0px;padding:0px"><tr style="margin:0px;padding:0px"><td style="margin:0px;padding:0.2em 0.5em;font-family:monospace;line-height:16.12px;vertical-align:top;white-space:nowrap;background:rgb(240,240,240)"><span style="margin:0px;padding:0px;float:left"><span style="margin:0px;padding:0px 0px 0px 14px;min-width:9px;min-height:9px;background-image:url();background-position:0% 50%;background-repeat:no-repeat"></span>Lit BaseType DBInt</span></td><td style="margin:0px;padding:0px 0px 0px 0.5em;vertical-align:top"> </td></tr><tr style="margin:0px;padding:0px"><td colspan="2" style="margin:0px;padding:0px 0px 0px 0.5em;vertical-align:top"><div style="margin:0px;padding:0px;display:inherit"><div style="margin:0px;padding:0px 0px 0px 2em"><p style="margin:0.8em 0px 0.4em;padding:0px;font-weight:bold;color:rgb(78,98,114)">Methods</p><p style="margin:0.8em 0px;padding:0.2em 0.5em;font-family:monospace;line-height:16.12px;border-top-width:1px;border-top-style:solid;border-top-color:rgb(204,204,204);background:rgb(240,240,240)">lit :: Col (TYPE Lifted) DBInt (AsHaskell DBInt) exprType -> Expr DBInt exprType</p></div></div></td></tr></tbody></table></div><br>But this is considerably less helpful:</div><div style="margin:0px;padding:0px 0px 0px 2em"><br></div><div style="margin:0px;padding:0px 0px 0px 2em">First, it seems to be broken, as it mentions the exprType variable, when is just DBint.</div><div style="margin:0px;padding:0px 0px 0px 2em"><br></div><div style="margin:0px;padding:0px 0px 0px 2em">Secondly, it mentions all sorts of kinds which are, in my opinion, unreadable in the current form. </div><div style="margin:0px;padding:0px 0px 0px 2em"><br></div><div style="margin:0px;padding:0px 0px 0px 2em">All of these problems would be solved if we just normalised this type family application as far as possible. What I <i>really</i> want to export is:</div><div style="margin:0px;padding:0px 0px 0px 2em"><br></div><div style="margin:0px;padding:0px 0px 0px 2em"><p style="font-size:13px;padding:0px 0px 0px 14px;font-weight:bold;color:rgb(78,98,114);font-family:sans-serif;line-height:18.2px;background-image:url();background-position:0px 0.4em;background-repeat:no-repeat">Instances</p><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px"><table style="margin:0px;padding:0px;font-size:inherit"><tbody style="margin:0px;padding:0px"><tr style="margin:0px;padding:0px"><td style="margin:0px;padding:0.2em 0.5em;font-family:monospace;line-height:16.12px;vertical-align:top;white-space:nowrap;background:rgb(240,240,240)"><span style="margin:0px;padding:0px;float:left"><span style="margin:0px;padding:0px 0px 0px 14px;min-width:9px;min-height:9px;background-image:url();background-position:0% 50%;background-repeat:no-repeat"></span>Lit DBInt</span></td><td style="margin:0px;padding:0px 0px 0px 0.5em;vertical-align:top"> </td></tr><tr style="margin:0px;padding:0px"><td colspan="2" style="margin:0px;padding:0px 0px 0px 0.5em;vertical-align:top"><div style="margin:0px;padding:0px;display:inherit"><div style="margin:0px;padding:0px 0px 0px 2em"><p style="margin:0.8em 0px 0.4em;padding:0px;font-weight:bold;color:rgb(78,98,114)">Methods</p><p style="margin:0.8em 0px;padding:0.2em 0.5em;font-family:monospace;line-height:16.12px;border-top-width:1px;border-top-style:solid;border-top-color:rgb(204,204,204);background:rgb(240,240,240)">lit :: Int -> Expr DBInt</p></div></div></td></tr></tbody></table><br></div><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px"><br></div><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px">This is the type I want my users to be aware of.</div><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px"><span style="line-height:18.2px"><br></span></div><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px"><span style="line-height:18.2px">Has this been discussed before? If not, how do people feel about this?</span></div><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px"><br></div><div style="font-size:13px;margin:0px;padding:0px;display:inherit;font-family:sans-serif;line-height:18.2px">Ollie</div></div></div></div>