more cross-package docs details

I cleaned up most of the loose edges.  I still need to design and implement the GADT records syntax (should be easy) ; I was thinking:

Here is an example of haddock’s record-display:

http://hackage.haskell.org/packages/archive/mtl/1.1.0.2/doc/html/Control-Monad-Cont.html#v%3ACont

and here’s for an ordinary data type:

http://www.haskell.org/ghc/docs/latest/html/libraries/base/Data-Maybe.html#t%3AMaybe

Notice that records can have documentation per-constructor-argument.

So we need to decide what syntax we want, since there’s a tension between displaying the type of the constructor itself (including any class contexts, as GHC just implemented syntax for!), and having a separate line on which to document each field.

I’m inclined to copy type information a bit and have it look like, for
data Foo a where
Bar :: Ord a => { f1 :: [a]  — ^ Some values.
} -> Foo a
,
Bar :: Ord a => [a] -> Foo a
f1 :: [a]     Some values.

Or maybe explicit forall “Bar :: forall a. Ord a => [a] -> Foo a” since it obviously needs to (conceptually) scope over the following fields.

-Isaac