Next Project, Move doc-parsing to from GHC to Haddock

I’ve done the first step now! I made a patch that turns the representation of HsDoc in GHC into a FastString rather than a parsed entity, and deleted the parsing code and made it compile.  (HaddockModInfo will need to be FastString-ized also.)

(By the way, this means parsing the interiors of the comments.  GHC will still be the one to recognize “– |”, “– ^” and so forth, for this phase of the project, and to attach them to the parsed declarations.)

Next comes the presumably harder part: add support in Haddock!  (at least the final-product will need to be full of #ifdefs, in order to keep supporting GHC < 6.11, also.)

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

Cross-package documentation going well!

A good deal of success!  Here is the current status of my loose edges… Plus I’m sure there are some inevitable syntax niceties (choosing when to display in GADT syntax for example), but using this approach, they can’t be perfect, only pretty-good.  (The approach is similar to going through Template Haskell except we found out that TH/Convert had some problems, such as producing RdrNames rather than Names, so I wrote the equivalent function to go directly from TyThing to HsDecl Name).  So:(tyThingToHsSyn :: TyThing -> LHsDecl Name) is done (except probably for a few corner cases) — it compiles and works! (under 6.11.something and 6.10.3; I just failed to install ghc-paths for 6.8.2[*]) Paste of my working module here:
http://hpaste.org/6717

[*]cabal install –with-compiler=ghc-6.8.2 ghc-paths
/tmp/ghc-paths-0.1.0.522545/ghc-paths-0.1.0.5/Setup.hs:7:7:
Could not find module `Distribution.Simple.PackageIndex’:

Important remaining corner cases include:
– It seems that TyCon needs to export a new function (tyConParent :: TyCon -> TyConParent), because there’s no way to get that info presently!
– (isFunTyCon tc || isPrimTyCon tc) : how the heck am I supposed to represent these in a TyClDecl? 🙂
– When the HsDecls tree contains something of type HsDoc, do I just leave it empty? Will Haddock-code need to / already does fill that in? I guess I’ll find that out once I test my code on more things…? or what?
– it looks like I neglected to implement class ATs yet.

Also, (parseName “Prelude.->”) crashed GHC with “isDataOcc: check me ->”, so I wasn’t able to test it yet 🙂 … or is it one of those syntaxes that’s so fixed that you’re not even allowed to export or import it, perhaps?

***

Also I succeeded at integrating it into Haddock.  Well, almost.  For module List, I have the English documentation being displayed where it should be, and I have the signature displayed: all the signatures are “() -> ()”, 😛 .  I still need to finish threading the Ghc monad through Haddock.Interface.Create so that I can call lookupName at the right times.
– foible: I needed to convert InstalledInterface’s (HsDoc DocName) to ExportDecl’s (HsDoc Name), so I had to essentially write fmap for HsDoc, because it’s lamely not an instance of class Functor.  Where should that fmap-code be put? (can it be derived yet?)
– In Haddock.Interface.Create:
-* Under what circumstances is (Map.lookup (nameModule t) instIfaceMap) == Nothing?  Is it if we haddock a package for which its dependencies are compiled, but not, themselves, haddocked?
-* I didn’t figure out where to get ExportDecl’s expItemInstances from (but I didn’t really look around for it yet)

okay that’s enough for the day! I need some sleep! And some feedback would be good.  Besides that, I do have a plan: Integrate the two pieces I just did; Test on lots more examples than just haskell98-List; fix the things that I obviously neglected; Make the code a bit more presentable.  Any big pieces I’m leaving out that we have to do before starting to integrate my code?  (well, hoping that there aren’t any more big unexpected things that break along the way, anyway)

-Isaac